clckernel 1.2.13 → 1.2.18

package/src/catalog.js

@@ -28,147 +28,152 @@ const SAFEGUARD_CATALOG = [
   { name: 'scan_secrets', labels: ['scan_secrets', 'scan_secrets.js', 'scan_secrets.py'],
     checks: 'Secret & private-key leak scan', verify: ['verify_secret_leaks', 'verify_no_hardcoded_secrets'],
     applies_when: 'always', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'scan_secrets.js+scan_secrets.py', manifest: true, planned: false },
+    phase: 'audit', file: 'scan_secrets.js+scan_secrets.py', manifest: true, planned: false, lens: 'security' },
 
   { name: 'check_architecture', labels: ['check_architecture', 'check_architecture.js', 'check_architecture.py'],
     checks: 'Clean Architecture layer / server-component boundaries', verify: ['verify_architecture_layers', 'verify_server_component_boundaries'],
     applies_when: 'frontend,backend', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_architecture.js+check_architecture.py', manifest: true, planned: false },
+    phase: 'audit', file: 'check_architecture.js+check_architecture.py', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'check_custom', labels: ['check_custom', 'check_custom.js', 'check_custom.py'],
     checks: 'User-defined regex rules from `.clc-forge.yml`', verify: ['verify_custom_rules', 'verify_user_defined_regex_rules'],
     applies_when: 'always', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_custom.js+check_custom.py', manifest: true, planned: false },
+    phase: 'audit', file: 'check_custom.js+check_custom.py', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'check_a11y', labels: ['check_a11y', 'check_a11y.js'],
     checks: 'ARIA + alt accessibility', verify: ['verify_a11y', 'verify_accessibility'],
     applies_when: 'frontend', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_a11y.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_a11y.js', manifest: true, planned: false, lens: 'correctness' },
 
   { name: 'check_ui_reuse', labels: ['check_ui_reuse', 'check_ui_reuse.js'],
     checks: 'UI primitive reuse from components/ui/', verify: ['verify_ui_reuse', 'verify_component_reuse'],
     applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_ui_reuse.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_ui_reuse.js', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'check_performance', labels: ['check_performance', 'check_performance.js'],
     checks: 'next/image + tree-shaking', verify: ['verify_performance', 'verify_image_optimization'],
     applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_performance.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_performance.js', manifest: true, planned: false, lens: 'performance' },
 
   { name: 'check_responsive', labels: ['check_responsive', 'check_responsive.js'],
     checks: 'Mobile-first responsiveness, fixed-width overflow & touch target size', verify: ['verify_responsive', 'verify_mobile_adaptability'],
     applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_responsive.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_responsive.js', manifest: true, planned: false, lens: 'performance' },
 
   { name: 'check_seo', labels: ['check_seo', 'check_seo.js'],
     checks: 'SEO metadata, OpenGraph, GEO tags, semantic HTML & LCP priority', verify: ['verify_seo', 'verify_geo_metadata', 'verify_core_web_vitals'],
     applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_seo.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_seo.js', manifest: true, planned: false, lens: 'performance' },
 
   { name: 'check_storybook', labels: ['check_storybook', 'check_storybook.js'],
     checks: 'Storybook coverage (`.stories.tsx`)', verify: ['verify_storybook_coverage'],
     applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_storybook.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_storybook.js', manifest: true, planned: false, lens: 'performance' },
 
   { name: 'check_api_contracts', labels: ['check_api_contracts', 'check_api_contracts.js'],
     checks: 'Zod response-schema parsing', verify: ['verify_api_contracts', 'verify_response_schemas'],
     applies_when: 'frontend', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_api_contracts.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_api_contracts.js', manifest: true, planned: false, lens: 'correctness' },
 
   { name: 'check_migrations', labels: ['check_migrations', 'check_migrations.py'],
     checks: 'Alembic/Django migration idempotency', verify: ['verify_migration_idempotency'],
     applies_when: 'backend,fastapi,django', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_migrations.py', manifest: true, planned: false },
+    phase: 'audit', file: 'check_migrations.py', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'verify_tdd', labels: ['verify_tdd', 'verify_tdd.py'],
     checks: 'Real red→green TDD validation', verify: ['verify_tdd_red_green', 'verify_tdd_evidence'],
     applies_when: 'backend', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'verify_tdd.py', manifest: false, planned: false },
+    phase: 'audit', file: 'verify_tdd.py', manifest: false, planned: false, lens: 'correctness' },
 
   { name: 'check_scope', labels: ['check_scope', 'check_scope.py'],
     checks: 'git-diff vs SDD-authorization scope guardrail', verify: ['verify_scope_authorization', 'verify_sdd_scope'],
     applies_when: 'always', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_scope.py', manifest: false, planned: false },
+    phase: 'audit', file: 'check_scope.py', manifest: false, planned: false, lens: 'correctness' },
 
   { name: 'celery_guard', labels: ['celery_guard', 'celery_guard.py'],
     checks: 'Broker URL exposure, ignore_result, result backend', verify: ['verify_celery_broker_config'],
     applies_when: 'celery', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'celery_guard.py', manifest: true, planned: false },
+    phase: 'audit', file: 'celery_guard.py', manifest: true, planned: false, lens: 'security' },
 
   { name: 'redis_guard', labels: ['redis_guard', 'redis_guard.py'],
     checks: 'decode_responses, connect timeout, hardcoded URLs', verify: ['verify_redis_config'],
     applies_when: 'redis', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'redis_guard.py', manifest: true, planned: false },
+    phase: 'audit', file: 'redis_guard.py', manifest: true, planned: false, lens: 'security' },
 
   { name: 'postgres_guard', labels: ['postgres_guard', 'postgres_guard.py'],
     checks: 'Raw SQL string formatting, hstore misuse', verify: ['verify_postgres_sql_usage'],
     applies_when: 'postgresql', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'postgres_guard.py', manifest: true, planned: false },
+    phase: 'audit', file: 'postgres_guard.py', manifest: true, planned: false, lens: 'security' },
 
   { name: 'docker_guard', labels: ['docker_guard', 'docker_guard.py'],
     checks: 'Non-root USER, ENV secrets, missing HEALTHCHECK', verify: ['verify_dockerfile_security'],
     applies_when: 'docker', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'docker_guard.py', manifest: true, planned: false },
+    phase: 'audit', file: 'docker_guard.py', manifest: true, planned: false, lens: 'security' },
 
   { name: 'check_symlinks', labels: ['check_symlinks', 'check_symlinks.js'],
     checks: 'AI IDE symlinks and rule mirror verification', verify: ['verify_symlinks', 'verify_rule_mirrors'],
     applies_when: 'agent-os', severity: 'error', gate_mode: 'hard', config_keys: ['scope'],
-    phase: 'audit', file: 'check_symlinks.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_symlinks.js', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'check_hitl', labels: ['check_hitl', 'check_hitl.js'],
     checks: 'Human-in-the-Loop review checkpoint validator in subagent skills', verify: ['verify_hitl', 'verify_human_review_checkpoints'],
     applies_when: 'agent-os', severity: 'error', gate_mode: 'hard', config_keys: ['scope'],
-    phase: 'audit', file: 'check_hitl.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_hitl.js', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'check_domain_data', labels: ['check_domain_data', 'check_domain_data.js'],
     checks: 'Domain deliverables schema and clean state integrity', verify: ['verify_domain_data', 'verify_clean_state_metrics'],
     applies_when: 'agent-os', severity: 'error', gate_mode: 'hard', config_keys: ['scope'],
-    phase: 'audit', file: 'check_domain_data.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_domain_data.js', manifest: true, planned: false, lens: 'architecture' },
+
+  { name: 'check_test_calendar_sync', labels: ['check_test_calendar_sync', 'check_test_calendar_sync.js'],
+    checks: 'Test calendar harness synchronization and parity check', verify: ['verify_calendar_sync', 'verify_test_calendar_sync'],
+    applies_when: 'agent-os', severity: 'error', gate_mode: 'hard', config_keys: ['scope'],
+    phase: 'audit', file: 'check_test_calendar_sync.js', manifest: true, planned: false, lens: 'performance' },
 
   { name: 'ruff', labels: ['ruff'],
     checks: 'Python AST linter (external CLI)', verify: ['verify_python_lint'],
     applies_when: 'backend', severity: 'warning', gate_mode: 'advisory', config_keys: [],
-    phase: 'test', file: null, manifest: true, planned: false },
+    phase: 'test', file: null, manifest: true, planned: false, lens: 'correctness' },
 
   { name: 'pytest', labels: ['pytest'],
     checks: 'Test runner (external CLI)', verify: ['verify_test_coverage'],
     applies_when: 'backend', severity: 'warning', gate_mode: 'advisory', config_keys: [],
-    phase: 'test', file: null, manifest: true, planned: false },
+    phase: 'test', file: null, manifest: true, planned: false, lens: 'correctness' },
 
   { name: 'tsc', labels: ['tsc'],
     checks: 'TypeScript typecheck (external)', verify: ['verify_typescript_types'],
     applies_when: 'frontend', severity: 'error', gate_mode: 'hard', config_keys: [],
-    phase: 'test', file: null, manifest: true, planned: false },
+    phase: 'test', file: null, manifest: true, planned: false, lens: 'correctness' },
 
   { name: 'lint', labels: ['lint', 'lint-staged'],
     checks: 'lint-staged (external)', verify: ['verify_lint_staged'],
     applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: [],
-    phase: 'test', file: null, manifest: true, planned: false },
+    phase: 'test', file: null, manifest: true, planned: false, lens: 'correctness' },
 
   { name: 'graphify', labels: ['graphify'],
     checks: 'Memory graph (external, graceful-skip)', verify: ['verify_memory_graph'],
     applies_when: 'always', severity: 'warning', gate_mode: 'advisory', config_keys: [],
-    phase: 'review', file: null, manifest: false, planned: false },
+    phase: 'review', file: null, manifest: false, planned: false, lens: 'architecture' },
 
   { name: 'gentle_ai_review', labels: ['gentle_ai_review', 'gentle-ai'],
     checks: 'Native bounded review gate (external, graceful-skip)', verify: ['verify_rdd_review_gate'],
     applies_when: 'always', severity: 'error', gate_mode: 'hard', config_keys: [],
-    phase: 'review', file: null, manifest: false, planned: false },
+    phase: 'review', file: null, manifest: false, planned: false, lens: 'architecture' },
 
   { name: 'check_openapi_drift', labels: ['check_openapi_drift', 'check_openapi_drift.py'],
     checks: 'FastAPI OpenAPI schema drift vs app routes', verify: ['verify_openapi_drift'],
     applies_when: 'fastapi', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_openapi_drift.py', manifest: true, planned: true },
+    phase: 'audit', file: 'check_openapi_drift.py', manifest: true, planned: true, lens: 'correctness' },
 
   { name: 'check_db_efficiency', labels: ['check_db_efficiency', 'check_db_efficiency.py'],
     checks: 'ORM N+1 / select_related / prefetch_related', verify: ['verify_db_efficiency', 'verify_no_n_plus_1'],
     applies_when: 'django|sqlalchemy', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_db_efficiency.py', manifest: true, planned: false },
+    phase: 'audit', file: 'check_db_efficiency.py', manifest: true, planned: false, lens: 'performance' },
 
   { name: 'check_observability', labels: ['check_observability', 'check_observability.py'],
     checks: 'structlog structured logging; bare print/logger ban', verify: ['verify_structured_logging'],
     applies_when: 'backend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_observability.py', manifest: true, planned: true },
+    phase: 'audit', file: 'check_observability.py', manifest: true, planned: true, lens: 'performance' },
 ];
 
 // Freeze the registry so config validation and generation can rely on it.
@@ -190,6 +195,9 @@ const VALID_APPLIES_WHEN = [
   'agent-os',
 ];
 
+/** Canonical 4 RDD Lenses */
+const VALID_LENSES = ['correctness', 'security', 'architecture', 'performance'];
+
 /** Normalize an input label for catalog lookup. */
 function normalizeLabel(name) {
   return typeof name === 'string' ? name.trim().toLowerCase() : '';
@@ -221,13 +229,21 @@ function gateFor(name) {
   return entry ? entry.gate_mode : null;
 }
 
+/** Canonical RDD review lens for a guard name/label; null when unknown. */
+function lensFor(name) {
+  const entry = applyTo(name);
+  return entry ? entry.lens : null;
+}
+
 module.exports = {
   SAFEGUARD_CATALOG,
   VALID_SEVERITIES,
   VALID_GATE_MODES,
   VALID_PHASES,
   VALID_APPLIES_WHEN,
+  VALID_LENSES,
   applyTo,
   severityFor,
   gateFor,
+  lensFor,
 };

package/src/config.js

@@ -4,7 +4,7 @@
  * never a silent fallback.
  */
 
-const { parseYaml } = require('./yaml.js');
+const { parseYaml } = require('../tools/yaml.js');
 const {
   SAFEGUARD_CATALOG,
   VALID_SEVERITIES,

package/src/generator.js

@@ -8,9 +8,33 @@ const path = require('path');
 const { execSync } = require('child_process');
 const { resolveConfig } = require('./config.js');
 
+/**
+ * Detects whether a Node CLI required by a hook command is actually installed
+ * in the target project. Resolving through node_modules/.bin is what `npx` does
+ * first, so a missing entry there means `npx` would download it on the fly (or
+ * fail inside a commit hook, where the network is not available).
+ * @param {string} targetDir - Target project root
+ * @param {string} pkg - Package name to look for
+ * @returns {boolean}
+ */
+function isCliInstalled(targetDir, pkg) {
+  if (!pkg) return false;
+  try {
+    return fs.existsSync(path.join(targetDir, 'node_modules', '.bin', pkg));
+  } catch (e) {
+    return false;
+  }
+}
+
 /**
  * Generates a pre-commit hook dynamically from the adapter's tool manifest.
  * Frontend projects use .husky; backend projects use .githooks.
+ *
+ * External CLIs (language === 'external', e.g. tsc, lint-staged) are only emitted
+ * when the target project already depends on them: the generator does not add
+ * dependencies, so referencing an uninstalled binary produces a hook that fails
+ * on every commit.
+ *
  * @param {object} adapter - Adapter with getTools() and projectType
  * @param {string} targetDir - Target project root
  */
@@ -23,10 +47,17 @@ function generateHookFromManifest(adapter, targetDir) {
     : path.join(targetDir, '.githooks');
   const hookFile = path.join(hookDir, 'pre-commit');
 
+  // The husky bootstrap only exists when the project ran `husky init`. Source it
+  // only in that case, so a generated hook never points at a missing file.
+  const huskyBootstrap = path.join(hookDir, '_', 'husky.sh');
+  const useHuskyBootstrap = isFront && fs.existsSync(huskyBootstrap);
+
   const lines = [];
   if (isFront) {
     lines.push('#!/usr/bin/env sh');
-    lines.push('. "$(dirname -- "$0")/_/husky.sh"');
+    if (useHuskyBootstrap) {
+      lines.push('. "$(dirname -- "$0")/_/husky.sh"');
+    }
     lines.push('');
   } else {
     lines.push('#!/usr/bin/env bash');
@@ -34,13 +65,26 @@ function generateHookFromManifest(adapter, targetDir) {
     lines.push('');
   }
 
+  const skipped = [];
   tools.forEach(tool => {
     if (!tool.command) return;
+    if (tool.language === 'external') {
+      if (!isCliInstalled(targetDir, tool.extCLI)) {
+        skipped.push(tool.extCLI || tool.command);
+        return;
+      }
+    }
     lines.push(tool.command);
   });
 
+  if (skipped.length > 0) {
+    lines.push('');
+    lines.push(`# Not run here (not a dependency of this project): ${skipped.join(', ')}`);
+    lines.push('# Install it and re-run `clckernel update` to enable it.');
+  }
+
   fs.mkdirSync(hookDir, { recursive: true });
-  fs.writeFileSync(hookFile, lines.join('\n'), 'utf-8');
+  fs.writeFileSync(hookFile, lines.join('\n') + '\n', 'utf-8');
   try { fs.chmodSync(hookFile, '755'); } catch (e) {}
 
   if (!isFront) {
@@ -62,6 +106,10 @@ function installToolsFromManifest(targetDir, manifest, config) {
   const sourceToolsDir = path.join(__dirname, '..', 'tools');
   const isFront = config.projectType === 'frontend';
 
+  // tools/ must exist before anything is copied into it. Provisioning a project
+  // that has no tools/ yet used to throw ENOENT on the first copyFileSync.
+  fs.mkdirSync(path.join(targetDir, 'tools'), { recursive: true });
+
   // Validate descriptors: skip + warn tools missing required fields
   const validTools = manifest.filter(tool => {
     if (!tool.name || !tool.language || !tool.command) {
@@ -72,7 +120,8 @@ function installToolsFromManifest(targetDir, manifest, config) {
   });
 
   // Always copy the audit orchestrator for the right language
-  const orchestrator = isFront ? 'audit.js' : 'audit.py';
+  const isNodeStack = config.projectType === 'frontend' || config.projectType === 'agent-os';
+  const orchestrator = isNodeStack ? 'audit.js' : 'audit.py';
   const orchestratorSrc = path.join(sourceToolsDir, orchestrator);
   const orchestratorDest = path.join(targetDir, 'tools', orchestrator);
   if (fs.existsSync(orchestratorSrc)) {
@@ -93,25 +142,29 @@ function installToolsFromManifest(targetDir, manifest, config) {
     }
   });
 
-  // check_custom.js requires the shared YAML parser (../src/yaml.js),
-  // so the generated project must ship it too.
+  // check_custom.js parses the project YAML config, so the generated project
+  // must ship the parser alongside it.
   if (validTools.some(tool => tool.path === 'check_custom.js')) {
-    installYamlModule(targetDir, sourceToolsDir);
+    installYamlModule(targetDir);
   }
 }
 
 /**
- * Copies the zero-dependency YAML parser into a generated project's src/.
- * Required by tools/check_custom.js (require('../src/yaml.js')).
+ * Copies the zero-dependency YAML parser into the target's tools/ directory.
+ *
+ * It deliberately does NOT go into the consumer's src/: that directory belongs
+ * to the project, and writing there both pollutes it and silently overwrites a
+ * consumer file that happens to be named yaml.js. tools/ is the directory the
+ * harness provisions and owns.
+ *
  * @param {string} targetDir - Target project root
- * @param {string} sourceToolsDir - Bundled tools/ directory of this package
  */
-function installYamlModule(targetDir, sourceToolsDir) {
-  const yamlSrc = path.join(sourceToolsDir, '..', 'src', 'yaml.js');
+function installYamlModule(targetDir) {
+  const yamlSrc = path.join(__dirname, '..', 'tools', 'yaml.js');
   if (!fs.existsSync(yamlSrc)) return;
-  const yamlDest = path.join(targetDir, 'src', 'yaml.js');
-  fs.mkdirSync(path.join(targetDir, 'src'), { recursive: true });
-  fs.copyFileSync(yamlSrc, yamlDest);
+  const toolsDest = path.join(targetDir, 'tools');
+  fs.mkdirSync(toolsDest, { recursive: true });
+  fs.copyFileSync(yamlSrc, path.join(toolsDest, 'yaml.js'));
 }
 
 /**
@@ -139,7 +192,7 @@ function installFallbackTools(targetDir) {
   });
 
   if (fallbackFiles.includes('check_custom.js')) {
-    installYamlModule(targetDir, sourceToolsDir);
+    installYamlModule(targetDir);
   }
 }
 
@@ -155,9 +208,12 @@ function generateFallbackHook(targetDir, projectType) {
     const hookDir = path.join(targetDir, '.husky');
     fs.mkdirSync(hookDir, { recursive: true });
     const hookFile = path.join(hookDir, 'pre-commit');
+    // Only source the husky bootstrap when the project actually has it.
+    const bootstrap = fs.existsSync(path.join(hookDir, '_', 'husky.sh'))
+      ? '. "$(dirname -- "$0")/_/husky.sh"\n'
+      : '';
     fs.writeFileSync(hookFile, `#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
+${bootstrap}
 node tools/scan_secrets.js || true
 `, 'utf-8');
     try { fs.chmodSync(hookFile, '755'); } catch (e) {}
@@ -434,19 +490,27 @@ function installAgenticCLI(targetDir) {
   symlinks.forEach(link => {
     const linkPath = path.join(targetDir, link);
     const linkDir = path.dirname(linkPath);
-    
+
     if (!fs.existsSync(linkDir)) {
       fs.mkdirSync(linkDir, { recursive: true });
     }
 
     const relPath = path.relative(linkDir, path.join(targetDir, sourceFile));
-    
+
     try {
+      // Only replace an existing symlink (a stale mirror needs refreshing).
+      // A regular file belongs to the consumer: unlinking it would destroy
+      // their own rules, so leave it in place instead.
+      let existing = null;
       try {
-        if (fs.lstatSync(linkPath)) {
-          fs.unlinkSync(linkPath);
-        }
+        existing = fs.lstatSync(linkPath);
       } catch (err) {}
+
+      if (existing) {
+        if (!existing.isSymbolicLink()) return;
+        fs.unlinkSync(linkPath);
+      }
+
       fs.symlinkSync(relPath, linkPath, 'file');
     } catch (e) {
       // Ignorar fallos de permisos o symlinks existentes

package/src/index.js

@@ -9,25 +9,110 @@ const { printBanner, printBox, promptOptions, printSuccess, colors } = require('
 const { generateHarness } = require('./generator');
 const { runDoctor } = require('./doctor');
 
+/** Commands that only read state. Safe to run against any project. */
+const READ_ONLY_COMMANDS = new Set(['help', '--help', '-h', 'version', '--version', '-v']);
+
+/**
+ * Flags that explicitly opt into the installation path. Everything else is
+ * rejected: a destructive default is fixed by making the default non-destructive.
+ */
+const INSTALL_FLAGS = new Set(['--yes', '-y']);
+
+const HELP_TEXT = `
+${'clckernel'} — CLC Kernel: The AI Agent Governance Engine
+
+USAGE
+  clckernel <command> [targetDir]
+
+READ-ONLY COMMANDS (never modify your project)
+  help, --help, -h        Show this help
+  version, --version, -v  Print the installed version
+  doctor [targetDir]      Run diagnostics on a project
+  update [targetDir]      Refresh tools, playbooks and IDE symlinks
+
+INSTALLATION (writes to the target project)
+  clckernel [targetDir] --yes   Provision the governance harness
+
+  Requires an explicit opt-in. Bare \`clckernel\` runs the interactive
+  confirmation flow; with no TTY it refuses to install.
+
+EXAMPLES
+  clckernel --help
+  clckernel doctor .
+  clckernel update .
+  clckernel . --yes
+`;
+
+/**
+ * Reject any input that is not a recognized command or install flag.
+ * The rejected tokens are echoed so the user can see what was not understood.
+ * @param {string[]} args - Raw argv (without node/script)
+ * @returns {number} Process exit code
+ */
+function rejectUnknownInput(args) {
+  const rejected = args.join(' ');
+  process.stderr.write(
+    `\n❌ Unknown input: ${rejected}\n` +
+      '   clckernel will not modify your project on unrecognized input.\n' +
+      '   Run `clckernel --help` to see available commands.\n\n'
+  );
+  return 1;
+}
+
 async function runCli() {
   const args = process.argv.slice(2);
   const command = args[0];
 
-  let targetDir = process.cwd();
-  if (command && !command.startsWith('-') && command !== 'doctor' && command !== 'update') {
-    targetDir = path.resolve(command);
+  if (command && READ_ONLY_COMMANDS.has(command)) {
+    if (command === 'version' || command === '--version' || command === '-v') {
+      const { version } = require('../package.json');
+      process.stdout.write(`clckernel v${version}\n`);
+    } else {
+      process.stdout.write(HELP_TEXT);
+    }
+    return;
+  }
+
+  if (args.some((a) => READ_ONLY_COMMANDS.has(a))) {
+    process.exitCode = rejectUnknownInput(args);
+    return;
   }
 
   if (command === 'doctor' || args.includes('--doctor')) {
-    if (args[1] && args[1] !== '--doctor') targetDir = path.resolve(args[1]);
-    runDoctor(targetDir);
+    const target = args[1] && args[1] !== '--doctor' ? args[1] : (args[0] === 'doctor' ? null : args[0]);
+    runDoctor(target ? path.resolve(target) : process.cwd());
     return;
   }
 
   if (command === 'update' || args.includes('--update')) {
-    if (args[1] && args[1] !== '--update') targetDir = path.resolve(args[1]);
+    const target = args[1] && args[1] !== '--update' ? args[1] : (args[0] === 'update' ? null : args[0]);
     const { runUpdate } = require('./updater');
-    await runUpdate(targetDir);
+    await runUpdate(target ? path.resolve(target) : process.cwd());
+    return;
+  }
+
+  // Everything below is destructive. Only reachable through an explicit command
+  // or an explicit install flag.
+  const flags = args.filter((a) => a.startsWith('-'));
+  const positionals = args.filter((a) => !a.startsWith('-'));
+  const unknownFlags = flags.filter((f) => !INSTALL_FLAGS.has(f));
+
+  if (unknownFlags.length > 0 || positionals.length > 1) {
+    process.exitCode = rejectUnknownInput(args);
+    return;
+  }
+
+  const targetDir = positionals.length === 1 ? path.resolve(positionals[0]) : process.cwd();
+  const explicitInstall = INSTALL_FLAGS.has(command) || flags.length > 0;
+  const isInteractive = Boolean(process.stdin.isTTY) && !process.env.CI;
+
+  if (!explicitInstall && !isInteractive) {
+    process.stderr.write(
+      '\n❌ Refusing to install without an explicit opt-in.\n' +
+        '   No TTY detected, so there is no confirmation prompt.\n' +
+        '   Re-run with `clckernel --yes` to provision, or `clckernel --help`.\n\n'
+    );
+    process.exitCode = 1;
     return;
   }