contextos-agents 2.0.0 → 2.1.1

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
@@ -121,9 +172,15 @@ 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.1.1'       # 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,167 @@
+/**
+ * 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}
+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()) {
+  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');
+
+    // 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 {
+      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`;
+    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,77 @@
+/**
+ * bin/commands/scan.js
+ * ContextOS CLI Command Handler: scan
+ *
+ * Runs security, placeholder, and write-scope checks against Git staged files.
+ */
+
+'use strict';
+
+const path = require('path');
+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 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: projectDir,
+    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(`  Scope Containment    : ${result.scope.status.toUpperCase()}`);
+  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 (Verification completed cleanly, no blocking violations)');
+  } 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' },
+    ],
+  },
 };
 
 /**