contextos-agents 2.0.0 → 2.1.0

package/README.md

@@ -1,13 +1,36 @@
-# <img src="./Frame%202.png" height="40" align="absmiddle" /> contextos-agents
-
-[![npm version](https://img.shields.io/npm/v/contextos-agents.svg)](https://www.npmjs.com/package/contextos-agents)
-[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
-[![CI](https://github.com/kok-o/contextos-agents/actions/workflows/validate-skills.yml/badge.svg)](https://github.com/kok-o/contextos-agents/actions/workflows/validate-skills.yml)
-
-**One version-controlled source of engineering rules for supported coding agents.**
-
-ContextOS is a deterministic context and policy compiler for AI coding agents. It transforms your team's version-controlled engineering rules into focused, verifiable context for Gemini, Claude Code, Cursor, GitHub Copilot, Aider, and Zed—and detects configuration drift in CI.
+<p align="center">
+  <a href="https://github.com/kok-o/contextos-agents">
+    <img src="./Frame%202.png" alt="ContextOS Logo" width="88" height="88" />
+  </a>
+</p>
+
+<h1 align="center">contextos-agents</h1>
+
+<p align="center">
+  <strong>One version-controlled source of engineering rules for supported coding agents.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/contextos-agents"><img src="https://img.shields.io/npm/v/contextos-agents?color=18181b&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/contextos-agents"><img src="https://img.shields.io/npm/dt/contextos-agents?color=18181b&logo=npm&label=downloads" alt="npm downloads" /></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D22.0.0-18181b?logo=node.js" alt="Node.js" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-18181b" alt="License" /></a>
+  <a href="https://github.com/kok-o/contextos-agents/actions/workflows/validate-skills.yml"><img src="https://img.shields.io/github/actions/workflow/status/kok-o/contextos-agents/validate-skills.yml?label=ci&color=18181b&logo=github" alt="CI" /></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="./GUIDE.md">Guide</a> •
+  <a href="./docs/product/onboarding.md">Onboarding</a> •
+  <a href="./docs/ADAPTER_COMPATIBILITY.md">Adapters</a> •
+  <a href="#supported-agents--compilation">Supported Agents</a> •
+  <a href="./CONTRIBUTING.md">Contributing</a> •
+  <a href="https://www.npmjs.com/package/contextos-agents">npm</a>
+</p>
+
+---
+
+ContextOS is a deterministic context and policy compiler for AI coding agents. It transforms your team's version-controlled engineering rules into focused, verifiable context for Gemini, Claude Code, Cursor, GitHub Copilot, Aider, and Zed - and detects configuration drift in CI.
 
 ## Installation
 
@@ -34,22 +57,24 @@ npx contextos-agents --skip-compile     # Skip auto-compilation step
 
 ## Why ContextOS?
 
-Most AI coding assistants suffer from two extremes: they either operate in a vacuum with zero knowledge of your architectural standards, or they are choked with massive monolithic system prompts that cause context overflow and lazy code stubs (`// TODO`).
+Modern development teams face fragmented AI tooling: engineers use Cursor, Claude Code, GitHub Copilot, Gemini, Zed, and Aider. Each tool requires its own proprietary rules format, leading to configuration drift, contradictory standards, and unvetted AI slop (`// TODO`, leaked secrets).
 
-**ContextOS is not another coding agent.** It governs the context and policies used by the agents your team already has.
+Artificially truncating skills to save tokens degrades model reasoning and induces hallucinations. Instead, ContextOS ensures that agents receive complete, high-fidelity engineering context from a single version-controlled source.
+
+**ContextOS is not another coding agent.** It is the deterministic context compiler and policy engine for the agents your team already uses.
 
 ### The Three Pillars
 
-1. **Portable:** Define your engineering rules once. ContextOS exports configurations for supported agents (Gemini, Claude Code, Cursor, Copilot, Aider, and Zed).
-2. **Focused:** The resolver selects rules and skills relevant to a task so agents receive less unrelated context.
-3. **Verifiable:** Lockfiles, provenance, drift detection, and CI gates make generated agent configuration reproducible and auditable.
+1. **Portable (Multi-Agent):** Define your engineering skills once in standard Markdown. ContextOS compiles native configurations for all supported agents (Gemini, Claude Code, Cursor, Copilot, Aider, and Zed).
+2. **High-Fidelity & Focused:** The resolver maps domain skills to relevant tasks without lossy truncation, delivering rich, complete context to the model.
+3. **Verifiable in CI:** Lockfile v2 provenance, dual-hash verification, and CI quality gates detect configuration drift and enforce quality guardrails before merge.
 
 ## How it works
 
 1. Define version-controlled engineering policies once.
-2. Resolve only the policies relevant to the current task.
+2. Resolve the complete, relevant skill policies for the current task.
 3. Compile native configuration for each coding agent.
-4. Detect configuration drift in CI.
+4. Detect configuration drift and policy violations in CI.
 
 ```bash
 contextos resolve "review authentication changes" \
@@ -62,10 +87,10 @@ Selected:
   engineering-workflow  required dependency
 
 Excluded:
-  context-manager       context budget
+  context-manager       domain relevance filter
 
 Risk: high
-Estimated context: 2,840 tokens
+Context status: complete and verified
 
 ## Dynamic Skill Resolution & Unified CLI (`contextos` / `ctx.js`)
 
@@ -108,9 +133,35 @@ contextos doctor
 contextos export all       # Compile for all agents
 ```
 
-### CI Quality Gate Action (`contextos-gate`)
+### Staged Index Security Scanner (`contextos scan`)
+
+Scan staged changes directly from the Git index for secret leaks, blocked credential files, unfinished lazy stubs, and write-scope containment:
+
+```bash
+contextos scan --staged --enforce
+contextos scan --staged --placeholders --scope .agents/task-scope.json --json
+```
+
+### Safe Git Pre-Commit Hooks (`contextos hook`)
+
+Install or remove isolated pre-commit hooks that run fast security checks without clobbering existing developer hooks:
+
+```bash
+contextos hook install
+contextos hook uninstall
+```
+
+### CI Quality Gate (`contextos gate`)
+
+Run the complete 8-point production quality gate locally:
+
+```bash
+contextos gate
+```
+
+### CI Quality Gate Action (contextos-gate)
 
-Guard your repository against skill drift, secret leaks, and rule regressions using the official GitHub Composite Action:
+Guard your repository against skill drift, missing outputs, and rule regressions using the official GitHub Composite Action:
 
 ```yaml
 # .github/workflows/pr-gate.yml
@@ -122,8 +173,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: kok-o/contextos-agents/.github/actions/contextos-gate@v2.0.0
+        with:
+          version: '2.0.0'       # Pinned version of contextos-agents runner
+          adapters: 'all'        # Adapters to verify (or specific: 'cursor', 'claude')
+          working-directory: '.' # Project root directory
 ```
 
+The action executes the verified ContextOS quality gate in-process from the pinned package version, verifying generated AI adapter configs against source skills without executing untrusted scripts from pull requests, and without requiring a Node.js project or running `npm test`.
+
 ## Optional MCP integration (Beta)
 
 The MCP server is a separate beta package. It is not part of the stable `contextos-agents` core.
@@ -137,9 +194,9 @@ npx contextos-mcp --dir .
 
 The MCP server is read-only by default. Runtime execution remains experimental and is outside the stable core scope.
 
-## Security — Third-Party Skills
+## Security - Third-Party Skills
 
-ContextOS skills are **executable context** — they become part of the system prompt that controls your AI agent's behavior. A malicious skill could instruct the AI agent to exfiltrate environment variables, modify files, or ignore your project's security policies.
+ContextOS skills are **executable context** - they become part of the system prompt that controls your AI agent's behavior. A malicious skill could instruct the AI agent to exfiltrate environment variables, modify files, or ignore your project's security policies.
 
 > [!CAUTION]
 > **Install skills only from repositories you trust as you would trust executable code.** Skills installed via `ctx.js skill add` from npm or GitHub are not sandboxed.

package/bin/commands/hook.js

@@ -0,0 +1,129 @@
+/**
+ * bin/commands/hook.js
+ * ContextOS Git Hook Installer & Lifecycle Manager
+ *
+ * Safely installs and uninstalls the pre-commit governance hook.
+ * Preserves pre-existing user hooks, supports core.hooksPath and worktrees,
+ * and operates idempotently.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { findHooksDir } = require('../lib/git-snapshot.js');
+
+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
+${HOOK_MARKER_END}`;
+
+function installHook(cwd = process.cwd()) {
+  const hooksDir = findHooksDir(cwd);
+
+  if (!hooksDir) {
+    console.error('[ERROR] Not a Git repository or Git hooks directory not found.');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+  }
+
+  const hookFile = path.join(hooksDir, 'pre-commit');
+
+  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}`);
+    } 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}`);
+    }
+  } else {
+    // Fresh hook installation with shebang
+    const fresh = `#!/bin/sh\n\n${HOOK_PAYLOAD}\n`;
+    fs.writeFileSync(hookFile, fresh, 'utf8');
+    console.log(`✓ ContextOS pre-commit hook installed in ${hookFile}`);
+  }
+
+  try {
+    fs.chmodSync(hookFile, 0o755);
+  } catch {
+    // Best effort on platforms that do not support POSIX file modes
+  }
+}
+
+function uninstallHook(cwd = process.cwd()) {
+  const hooksDir = findHooksDir(cwd);
+
+  if (!hooksDir) {
+    console.error('[ERROR] Not a Git repository or Git hooks directory not found.');
+    process.exit(1);
+  }
+
+  const hookFile = path.join(hooksDir, 'pre-commit');
+
+  if (!fs.existsSync(hookFile)) {
+    console.log('✓ No pre-commit hook found to uninstall.');
+    return;
+  }
+
+  const existing = fs.readFileSync(hookFile, 'utf8');
+
+  if (!existing.includes(HOOK_MARKER_START)) {
+    console.log('✓ No ContextOS hook block detected in pre-commit hook.');
+    return;
+  }
+
+  // Remove exclusively the ContextOS demarcated block
+  const regex = new RegExp(`\\n?${HOOK_MARKER_START}[\\s\\S]*?${HOOK_MARKER_END}\\n?`, 'g');
+  const remaining = existing.replace(regex, '').trim();
+
+  // If file contains only shebang or is empty, remove it completely
+  if (!remaining || remaining === '#!/bin/sh' || remaining === '#!/bin/bash') {
+    fs.unlinkSync(hookFile);
+    console.log(`✓ ContextOS pre-commit hook uninstalled and empty ${hookFile} removed.`);
+  } else {
+    // Preserve remaining user scripts
+    fs.writeFileSync(hookFile, remaining + '\n', 'utf8');
+    console.log(`✓ ContextOS block removed from ${hookFile}; user commands preserved.`);
+  }
+}
+
+function hookCommand(args, flags) {
+  const subCommand = args[1] ? args[1].toLowerCase().trim() : null;
+
+  if (subCommand === 'install') {
+    installHook(process.cwd());
+    process.exit(0);
+  } else if (subCommand === 'uninstall') {
+    uninstallHook(process.cwd());
+    process.exit(0);
+  } else {
+    console.log('\nUsage: contextos hook <install|uninstall>\n');
+    console.log('Commands:');
+    console.log('  install    Safely install pre-commit quality gate hook');
+    console.log('  uninstall  Remove ContextOS block while preserving custom hooks\n');
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  installHook,
+  uninstallHook,
+  hookCommand,
+  HOOK_MARKER_START,
+  HOOK_MARKER_END,
+  HOOK_PAYLOAD,
+};

package/bin/commands/scan.js

@@ -0,0 +1,70 @@
+/**
+ * bin/commands/scan.js
+ * ContextOS CLI Command Handler: scan
+ *
+ * Runs security, placeholder, and write-scope checks against Git staged files.
+ */
+
+'use strict';
+
+const { runScan } = require('../lib/scan.js');
+
+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');
+  const checkSecrets = !args.includes('--no-secrets');
+
+  const scopeIdx = args.indexOf('--scope');
+  const scopeFile = scopeIdx !== -1 && args[scopeIdx + 1] ? args[scopeIdx + 1] : null;
+
+  const result = runScan({
+    cwd: process.cwd(),
+    staged: true,
+    secrets: checkSecrets,
+    placeholders: checkPlaceholders,
+    scope: scopeFile,
+    enforce,
+  });
+
+  if (isJson) {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.code);
+  }
+
+  console.log('\n══════════════════════════════════════════════════════');
+  console.log('  ContextOS Staged Index Scanner');
+  console.log('══════════════════════════════════════════════════════\n');
+
+  if (result.code === 2) {
+    console.error(`  [ERROR] ${result.error || 'Scan incomplete'}\n`);
+    process.exit(2);
+  }
+
+  console.log(`  Staged Files Scanned : ${result.stats.stagedFilesCount}`);
+  console.log(`  Enforcement Mode     : ${enforce ? 'STRICT (fails on findings)' : 'ADVISORY (warnings only)'}`);
+  console.log(`  Violations Found     : ${result.stats.violationsCount}\n`);
+
+  if (result.findings.length > 0) {
+    console.log('  Findings:');
+    for (const f of result.findings) {
+      const loc = f.line ? `${f.file}:${f.line}` : f.file;
+      const tag = f.severity === 'error' ? 'ERROR' : 'WARN';
+      console.log(`    • [${f.ruleId}] [${tag}] ${loc}`);
+      console.log(`      ${f.details}`);
+    }
+    console.log('');
+  }
+
+  console.log('──────────────────────────────────────────────────────');
+  if (result.ok) {
+    console.log('  RESULT: PASSED (No blocking violations in staged index)');
+  } else {
+    console.log('  RESULT: FAILED (Commit blocked due to staged violations)');
+  }
+  console.log('──────────────────────────────────────────────────────\n');
+
+  process.exit(result.code);
+}
+
+module.exports = scanCommand;

package/bin/commands.js

@@ -195,13 +195,28 @@ const COMMAND_REGISTRY = {
     requiresProject: true,
     options: [],
   },
+  gate: {
+    name: 'gate',
+    description: 'Run quality gate validation and drift checks without disk mutation',
+    usage: 'contextos gate [--project <dir>] [--target <adapters>] [--profile <name>] [--json]',
+    requiresProject: false,
+    options: [
+      { flag: '--project <dir>', desc: 'Target project directory (default: cwd)' },
+      { flag: '--target <adapters>', desc: 'Adapters to verify (gemini, claude, cursor, copilot, aider, zed, all)' },
+      { flag: '--profile <name>', desc: 'Profile override for verification' },
+      { flag: '--json', desc: 'Output gate report in versioned JSON format' },
+    ],
+  },
   export: {
     name: 'export',
     description: 'Compile skills for target agent (gemini, claude, cursor, copilot, aider, zed, all)',
-    usage: 'contextos export <target> [--profile <name>]',
+    usage: 'contextos export <target> [--check] [--project <dir>] [--profile <name>] [--json]',
     requiresProject: true,
     options: [
+      { flag: '--check', desc: 'Verify synchronization without modifying disk' },
+      { flag: '--project <dir>', desc: 'Target project directory (default: cwd)' },
       { flag: '--profile <name>', desc: 'Apply profile for this export run' },
+      { flag: '--json', desc: 'Output in JSON format' },
     ],
   },
   profile: {
@@ -293,6 +308,29 @@ const COMMAND_REGISTRY = {
       { flag: '--continue [txId]', desc: 'Attempt to resume and complete prepared transaction' },
     ],
   },
+  scan: {
+    name: 'scan',
+    description: 'Scan Git staged index for secrets, lazy stubs, and write-scope containment',
+    usage: 'contextos scan [--staged] [--secrets] [--placeholders] [--scope <file>] [--enforce] [--json]',
+    requiresProject: false,
+    options: [
+      { flag: '--staged', desc: 'Scan staged changes in Git index (default)' },
+      { flag: '--placeholders', desc: 'Detect unfinished lazy placeholder stubs in newly added code' },
+      { flag: '--scope <file>', desc: 'Verify staged files stay within declared task scope JSON' },
+      { flag: '--enforce', desc: 'Fail with exit code 1 if violations are detected' },
+      { flag: '--json', desc: 'Output scan results in versioned JSON format' },
+    ],
+  },
+  hook: {
+    name: 'hook',
+    description: 'Manage safe pre-commit Git governance hooks',
+    usage: 'contextos hook <install|uninstall>',
+    requiresProject: false,
+    options: [
+      { flag: 'install', desc: 'Install or update isolated pre-commit hook' },
+      { flag: 'uninstall', desc: 'Remove ContextOS hook block while preserving custom hooks' },
+    ],
+  },
 };
 
 /**

package/bin/index.js

@@ -32,6 +32,15 @@ const flags = {
     const i = args.indexOf('--add-skill');
     return i !== -1 ? args[i + 1] : null;
   })(),
+  project:     (() => {
+    const i = args.indexOf('--project');
+    return i !== -1 && args[i + 1] && !args[i + 1].startsWith('-') ? path.resolve(args[i + 1]) : process.cwd();
+  })(),
+  target:      (() => {
+    const i = args.indexOf('--target');
+    return i !== -1 && args[i + 1] && !args[i + 1].startsWith('-') ? args[i + 1] : null;
+  })(),
+  githubAnnotations: args.includes('--github-annotations'),
 };
 
 // ── Help / Version ────────────────────────────────────────────────────────────
@@ -64,12 +73,16 @@ Options:
   --minimal           Install only 7 core skills (lightweight footprint)
   --profile <name>    Install a specific profile (mvp, startup, enterprise, frontend, backend)
   --auto              Auto-detect tech stack and apply recommended profile
+  --project <path>    Specify target project root directory (default: current directory)
+  --target <adapters> Target adapter(s) to verify or export (default: all)
+  --github-annotations Emit GitHub Actions workflow commands and step summary
   --with-mcp, --mcp   [DEPRECATED] Use the separate @contextos/mcp package instead
   --skip-compile      Skip running ctx.js export after installation
   --add-skill <ref>   Install a community plugin skill after setup
 
 Commands:
   init                Install and configure .agents/ in target project
+  gate                Run deterministic quality gate against adapter drift
   status              Display project configuration, active profile, and lockfile status
   update              Safely update skills without overwriting custom changes
   uninstall           Safely uninstall ContextOS files (preserves user custom skills)
@@ -84,6 +97,10 @@ Commands:
   watch               Start continuous file watcher and auto-sync daemon
   detect              Analyze project and display detected tech stack & IDE
   install-skill       Interactive skill installer (or pass <ref> / --from-repo)
+  scan                Scan Git staged changes for secrets, placeholders, and scope
+  hook <cmd>          Manage isolated pre-commit Git governance hooks (install, uninstall)
+  recover             List or recover from interrupted filesystem transactions
+  explain [rule]      Inspect rule catalog, enforcement levels, and checkers
   setup-mcp           [DEPRECATED] Add MCP execution server to an existing .agents/ project
 
 Profiles:
@@ -250,20 +267,138 @@ if (mainCommand === 'recover') {
   process.exit(0);
 }
 
-// Proxy commands to .agents/ctx.js when executed in a ContextOS project
+// 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');
+  const result = runGate(flags.project, {
+    target,
+    profile: flags.profile,
+    json: flags.json,
+  });
+
+  if (process.env.GITHUB_ACTIONS === 'true' || flags.githubAnnotations) {
+    emitGitHubAnnotations(result);
+    writeGitHubSummary(result);
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`\nContextOS Quality Gate (${result.schemaVersion})\n`);
+    console.log(`  Project: ${result.projectRoot}`);
+    console.log(`  Status : ${result.status.toUpperCase()} (code ${result.code})`);
+    console.log(`  Message: ${result.message}\n`);
+    if (result.drift && result.drift.hasDrift) {
+      console.log(`! Drift detected (${result.drift.totalFindings} findings):`);
+      for (const [state, items] of Object.entries(result.drift.findings)) {
+        if (items.length > 0) {
+          console.log(`  [${state}] (${items.length}):`);
+          for (const item of items) {
+            console.log(`    • ${item.path || item.reason || JSON.stringify(item)}`);
+          }
+        }
+      }
+      if (result.drift.collisions && result.drift.collisions.length > 0) {
+        console.log(`\n  [PATH_COLLISIONS] (${result.drift.collisions.length}):`);
+        for (const c of result.drift.collisions) {
+          console.log(`    • ${c.path} (between ${c.firstAdapter} and ${c.secondAdapter})`);
+        }
+      }
+    }
+  }
+  process.exit(result.code);
+}
+
+// Export check mode (in-process verification without spawning untrusted project scripts)
+if (mainCommand === 'export' && args.includes('--check')) {
+  const { detectDrift } = require('../.agents/adapters/drift-detector.js');
+  const rawTarget = flags.target || (args[1] && !args[1].startsWith('-') ? args[1] : 'all');
+  const drift = detectDrift(flags.project, rawTarget, { profile: flags.profile });
+
+  if (process.env.GITHUB_ACTIONS === 'true' || flags.githubAnnotations) {
+    const { emitGitHubAnnotations, writeGitHubSummary } = require('./lib/gate.js');
+    const gateFormat = {
+      ok: !drift.hasDrift && !drift.hasError,
+      code: drift.code !== undefined ? drift.code : (drift.hasDrift ? 1 : 0),
+      status: drift.status || (drift.hasError ? 'error' : (drift.hasDrift ? 'drift' : 'pass')),
+      projectRoot: flags.project,
+      target: rawTarget,
+      profile: flags.profile || 'default',
+      drift,
+      message: drift.hasDrift ? 'Adapter drift detected' : 'Artifacts synchronized',
+    };
+    emitGitHubAnnotations(gateFormat);
+    writeGitHubSummary(gateFormat);
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(drift, null, 2));
+  } else {
+    console.log('\nContextOS - Adapter Output Drift Check\n');
+    console.log(`  Project: ${flags.project}`);
+    if (!drift.hasDrift && !drift.hasError) {
+      console.log(`✓ No adapter drift detected. All ${drift.projectedCount} output artifacts are synchronized.`);
+    } else {
+      console.log(`! Drift detected (${drift.totalFindings} finding(s)):\n`);
+      for (const [state, items] of Object.entries(drift.findings)) {
+        if (items.length > 0) {
+          console.log(`  [${state}] (${items.length}):`);
+          for (const item of items) {
+            console.log(`    • ${item.path || item.reason || JSON.stringify(item)}`);
+          }
+        }
+      }
+      if (drift.collisions && drift.collisions.length > 0) {
+        console.log(`\n  [PATH_COLLISIONS] (${drift.collisions.length}):`);
+        for (const c of drift.collisions) {
+          console.log(`    • ${c.path} (between ${c.firstAdapter} and ${c.secondAdapter})`);
+        }
+      }
+      console.log('\nRun: contextos export all    to synchronize outputs with source skills.\n');
+    }
+  }
+  process.exit(drift.code !== undefined ? drift.code : (drift.hasDrift ? 1 : 0));
+}
+
+// Scan command (Git staged index security and placeholder scanner)
+if (mainCommand === 'scan') {
+  const scanModule = require('./commands/scan.js');
+  scanModule(args, flags);
+  process.exit(0);
+}
+
+// Hook command (safe Git hook lifecycle management)
+if (mainCommand === 'hook') {
+  const { hookCommand } = require('./commands/hook.js');
+  hookCommand(args, flags);
+  process.exit(0);
+}
+
+// Proxy commands to trusted package .agents/ctx.js targeting flags.project
 const PROXY_COMMANDS = [
   'profile', 'export', 'validate', 'resolve', 'skill', 'index',
   'clean-worktrees', 'stats', 'watch', 'compile', 'explain',
   'thread'
 ];
 
-const ctxPath = path.join(process.cwd(), '.agents', 'ctx.js');
-const hasLocalCtx = fs.existsSync(ctxPath);
+const packageCtxPath = path.join(__dirname, '..', '.agents', 'ctx.js');
 
-if (mainCommand && PROXY_COMMANDS.includes(mainCommand) && hasLocalCtx) {
+if (mainCommand && PROXY_COMMANDS.includes(mainCommand)) {
   const { execFileSync } = require('child_process');
+  const filteredArgs = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--project') {
+      i++; // skip project path
+      continue;
+    }
+    filteredArgs.push(args[i]);
+  }
   try {
-    execFileSync(process.execPath, [ctxPath, ...args], { stdio: 'inherit' });
+    execFileSync(process.execPath, [packageCtxPath, ...filteredArgs], {
+      cwd: flags.project,
+      stdio: 'inherit',
+    });
   } catch (e) {
     process.exit(e.status || 1);
   }
@@ -300,34 +435,7 @@ if (mainCommand === 'watch') {
   watchModule.runWatch(process.cwd());
 }
 
-const PROJECT_ONLY_COMMANDS = ['profile', 'export', 'validate', 'resolve', 'skill', 'index', 'clean-worktrees', 'compile', 'explain'];
-if (mainCommand && PROJECT_ONLY_COMMANDS.includes(mainCommand) && !hasLocalCtx) {
-  console.error('[ERROR] .agents/ctx.js not found in current directory.');
-  console.error('        Are you in a ContextOS project? Run `contextos` or `npx contextos-agents` first.');
-  process.exit(1);
-}
-
-if (mainCommand === 'audit') {
-  if (!hasLocalCtx) {
-    console.error('[ERROR] .agents/ctx.js not found. Are you in a ContextOS project?');
-    process.exit(1);
-  }
-  const { execFileSync } = require('child_process');
-  try {
-    execFileSync(process.execPath, [ctxPath, 'validate'], { stdio: 'inherit' });
-  } catch (e) {
-    process.exit(1);
-  }
-  process.exit(0);
-}
-
 if (mainCommand === 'install-skill') {
-  const ctxPath = path.join(process.cwd(), '.agents', 'ctx.js');
-  if (!fs.existsSync(ctxPath)) {
-    console.error('[ERROR] .agents/ctx.js not found. Are you in a ContextOS project?');
-    process.exit(1);
-  }
-  
   const fromRepo = (() => {
     const i = args.indexOf('--from-repo');
     return i !== -1 ? args[i + 1] : null;
@@ -338,7 +446,10 @@ if (mainCommand === 'install-skill') {
   if (ref) {
     const { execFileSync } = require('child_process');
     try {
-      execFileSync(process.execPath, [ctxPath, 'skill', 'add', ref], { stdio: 'inherit' });
+      execFileSync(process.execPath, [packageCtxPath, 'skill', 'add', ref], {
+        cwd: flags.project,
+        stdio: 'inherit',
+      });
     } catch (e) {
       process.exit(1);
     }