clckernel 1.2.12 → 1.2.17

package/.agents/skills/clckernel_cli/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: clckernel-cli
+description: >-
+  Conversational Agent Governance & Universal CLI Orchestrator for CLC Kernel.
+  Use when the user issues a clckernel command (e.g. clckernel feature, clckernel fix,
+  clckernel audit, clckernel doctor, clckernel commit, clckernel update, clckernel start)
+  or /clckernel, or asks to initiate a feature, fix a bug, audit architecture, run tests,
+  diagnose health, or commit changes in a project governed by CLC Kernel.
+---
+
+# 🤖 CLC Kernel — Agent Governance Engine
+
+You are the runtime orchestrator of **CLC Kernel**. Your mission is to provide rigorous, deterministic AI agent governance across polyglot ecosystems (Next.js, FastAPI, Django, Astro, Rails, Go, Rust, Laravel, Agent-OS).
+
+When the developer issues a \`clckernel <command>\` or \`/clckernel <command>\` prompt, enter the designated state machine and execute its playbook without skipping steps.
+
+## Commands
+
+| Command | Category | Description | Reference |
+|---|---|---|---|
+| `feature` | Lifecycle | Execute full AIUP cycle for a new feature (Spec -> HIT -> TDD -> Clean Code -> Audit) | [reference/feature.md](reference/feature.md) |
+| `fix` | Lifecycle | Reproduce root cause with failing test, execute surgical fix, and audit | [reference/fix.md](reference/fix.md) |
+| `test` | Verification | Run stack test runner and verify clean green exit code | [reference/test.md](reference/test.md) |
+| `audit` | Verification | Run mandatory educational audit gate & AST validation | [reference/audit.md](reference/audit.md) |
+| `doctor` | Diagnostics | Check configuration health, hook parity, symlinks & AST engine | [reference/doctor.md](reference/doctor.md) |
+| `commit` | Version Control | Pre-flight audit, verify SDD scope, and commit with Conventional Commits | [reference/commit.md](reference/commit.md) |
+| `update` | Maintenance | Non-destructive update: refresh core tools, playbooks & symlinks (preserves SDDs & custom guards) | [reference/update.md](reference/update.md) |
+| `start` | Setup | Discover tech stack & initialize `.clckernel.yaml` | [reference/start.md](reference/start.md) |
+| `create_guard` | Safeguards | Scaffold a new AST/linter guard in native stack language | [reference/guard.md](reference/guard.md) |
+| `remove_guard` | Safeguards | Safely remove an existing guard and clean up config | [reference/guard.md](reference/guard.md) |
+| `phase` | Lifecycle | Add or remove pipeline execution phases | [reference/phase.md](reference/phase.md) |
+
+## Routing & Execution Rules
+
+1. **Explicit command (e.g. `clckernel feature auth`, `clckernel fix button`, `clckernel audit`):**
+   Immediately load the corresponding playbook from `reference/` and execute its phases sequentially. Never skip the red TDD phase or the audit gate.
+2. **General query or no arguments:**
+   Present available commands table and ask what action to perform.
+3. **Natural language intent:**
+   - *"Nueva funcionalidad / feature"* -> Route to `feature` ([reference/feature.md](reference/feature.md))
+   - *"Corregir bug / arreglar error"* -> Route to `fix` ([reference/fix.md](reference/fix.md))
+   - *"Correr tests / pruebas"* -> Route to `test` ([reference/test.md](reference/test.md))
+   - *"Auditar / verificar arquitectura"* -> Route to `audit` ([reference/audit.md](reference/audit.md))
+   - *"Revisar estado / diagnóstico"* -> Route to `doctor` ([reference/doctor.md](reference/doctor.md))
+   - *"Commitear / guardar cambios"* -> Route to `commit` ([reference/commit.md](reference/commit.md))
+4. **Mandatory Audit Gate:** Never declare success on code changes without running the audit gate and outputting the summary.

package/.agents/skills/clckernel_cli/reference/audit.md

@@ -0,0 +1,16 @@
+# Playbook: Mandatory Educational Audit Gate
+
+Use this playbook when auditing code quality, architecture compliance, or executing the mandatory audit gate (via `/clc audit`, `/clckernel audit`, or conversational request like *"corré la auditoría del kernel"*).
+
+## Execution
+
+1. **Locate Audit Tool:** Check available audit scripts:
+   - `node tools/audit.js` (JavaScript / Node environment)
+   - `python tools/audit.py` (Python / Backend environment)
+2. **Execute Audit:** Run the tool within project workspace.
+3. **Educational Summary:** Output the educational audit summary highlighting:
+   - AST Architectural conformance
+   - TDD compliance & test coverage
+   - Security & Secrets scan results
+   - Performance / DB efficiency checks
+4. **Actionable Feedback:** If any guard fails, explain the exact violation, why it breaches architectural invariants, and how to remediate it.

package/.agents/skills/clckernel_cli/reference/commit.md

@@ -0,0 +1,23 @@
+# 📦 Playbook: \`clckernel commit <message>\`
+
+Safely commit changes after verifying all pre-flight quality and architecture gates.
+
+## Mandatory Execution Protocol
+
+### Step 1: Pre-Flight AST Audit
+1. Run \`node tools/audit.js\` or \`python tools/audit.py\`.
+2. Ensure 100% of discovered guards pass with 0 errors and 0 secret leaks.
+
+### Step 2: Scope Verification
+1. Compare \`git diff --cached\` (or unstaged diff) against the active SDD spec in \`sdds/{change}/\`.
+2. Verify that no files outside the agreed feature scope are staged.
+
+### Step 3: Conventional Commit Formatting
+1. Format commit message according to Conventional Commits:
+   - \`feat(...): ...\`
+   - \`fix(...): ...\`
+   - \`refactor(...): ...\`
+   - \`test(...): ...\`
+   - \`docs(...): ...\`
+2. **STRICT LAW:** NEVER add "Co-Authored-By", AI signatures, or AI attribution.
+3. Stage required files and commit cleanly.

package/.agents/skills/clckernel_cli/reference/doctor.md

@@ -0,0 +1,10 @@
+# Playbook: Kernel Doctor & Diagnostics
+
+Use this playbook to diagnose environment health, detect hook drift, or verify configuration integrity (via `/clc doctor`, `/clckernel doctor`, or conversational request like *"revisá el estado del kernel"*).
+
+## Checks
+
+1. **Config Integrity:** Validate `.clckernel.yaml` syntax and presence of required sections (`framework`, `language`, `project_type`, `safeguards`).
+2. **Hook Parity:** Check that git hooks (`.githooks/pre-commit` or `.husky/pre-commit`) are installed and executable (`chmod +x`).
+3. **Tools & Guards Health:** Verify that scripts referenced in `.clckernel.yaml` exist in `tools/` and run without syntax errors.
+4. **Drift Remediation:** If drift is detected, offer automatic fix or report clear steps.

package/.agents/skills/clckernel_cli/reference/feature.md

@@ -0,0 +1,38 @@
+# 🚀 Playbook: \`clckernel feature <name>\`
+
+Guide the developer through implementing a new feature strictly governed by the **AI Unified Process (AIUP)**.
+
+## Mandatory Execution Protocol
+
+### Step 1: Research & Impact Analysis
+1. Inspect the codebase, existing modules, and architecture layers before writing any code.
+2. Determine affected architectural layers (Domain, Use Cases, Infrastructure, Presentation).
+
+### Step 2: Local SDD Specification
+1. Create a local specification file at \`sdds/{name}/spec.md\` (or \`sdds/{name}/01-spec.md\`).
+2. Document:
+   - Feature purpose and user requirements.
+   - API / Domain contracts and interfaces.
+   - Affected files and strict layer boundaries.
+   - Planned test scenarios (unit, integration, edge cases).
+
+### Step 3: Human-in-the-Loop (HIT) Review Gate
+1. Present the proposed SDD spec, contracts, and test scenarios directly to the user in chat.
+2. **STOP.** Explicitly ask for developer confirmation:
+   > *"Review the proposed contracts and test scenarios above. Shall we proceed to the Red TDD phase?"*
+3. Wait for the user's approval before touching any production source files.
+
+### Step 4: TDD Red Phase (Failing Test)
+1. Write a failing regression or unit test demonstrating the new feature requirement.
+2. Run the test suite and verify it fails with a non-zero exit code.
+3. Confirm that the failure message proves the feature is missing or non-functional.
+
+### Step 5: Clean Implementation (Green Phase)
+1. Implement the minimal clean code necessary to make the failing test pass.
+2. Maintain strict Clean Architecture boundaries (Domain -> Use Case -> Infrastructure).
+3. Re-run tests to confirm 100% green pass.
+
+### Step 6: Mandatory AST Audit Gate
+1. Execute \`node tools/audit.js\` or \`python tools/audit.py\`.
+2. Output the Educational Summary table to stdout.
+3. Verify zero secrets, zero layer violations, and zero N+1 queries.

package/.agents/skills/clckernel_cli/reference/fix.md

@@ -0,0 +1,24 @@
+# 🔧 Playbook: \`clckernel fix <issue>\`
+
+Enforce deterministic bug fixing without quick-fix shortcuts or superficial patches.
+
+## Mandatory Execution Protocol
+
+### Step 1: Root Cause & Traceback Analysis
+1. Analyze the issue description, error logs, and stack trace.
+2. Inspect the relevant files and surrounding architecture to pinpoint the exact failure mechanism.
+3. **DO NOT** edit source code directly to "try things out".
+
+### Step 2: TDD Red Phase (Regression Test)
+1. Write a focused test that reproduces the bug demonstrably.
+2. Run the test and verify it fails with the exact error described.
+3. Log the failure output as proof of regression reproduction.
+
+### Step 3: Surgical Clean Architecture Fix (Green Phase)
+1. Apply the minimal surgical change addressing the root cause.
+2. Respect layer isolation: do not bypass Domain or Use Case rules for convenience.
+3. Run the regression test and confirm it passes in green.
+
+### Step 4: Mandatory Audit Gate
+1. Execute \`node tools/audit.js\` or \`python tools/audit.py\`.
+2. Output the Educational Summary table to verify no side effects or guard violations occurred.

package/.agents/skills/clckernel_cli/reference/guard.md

@@ -0,0 +1,23 @@
+# Playbook: Safeguards Management (Create & Remove)
+
+Use this playbook when the user wants to add, modify, or delete custom architecture/security guards (via `/clc create_guard`, `/clc remove_guard`, or natural language like *"creá un guard para bloquear imports prohibidos"*).
+
+## 🛠️ Create Guard
+
+1. **Clarify Objective:** If not specified, ask what AST node, pattern, or security risk to intercept. **STOP.** Wait for details.
+2. **Native Language Implementation:** Write the guard script in the native stack language:
+   - Python projects -> Python `ast` script in `tools/guards/<name>_guard.py`
+   - Node / TS projects -> JS/TS script in `tools/guards/<name>_guard.js`
+   - Go projects -> Go `go/parser` / `ast` script
+   - Ruby projects -> Ruby `parser` gem script
+3. **Register in Config:** Add the guard definition under `custom_safeguards` or `tools` in `.clckernel.yaml`.
+4. **Validation:** Run the script against test fixtures to confirm it flags violations and exits cleanly on compliant code.
+
+---
+
+## 🗑️ Remove Guard
+
+1. Identify the target guard from user request or ask for confirmation.
+2. Update `.clckernel.yaml` removing the guard entry.
+3. If requested, delete the corresponding file from `tools/guards/`.
+4. Confirm removal cleanly.

package/.agents/skills/clckernel_cli/reference/phase.md

@@ -0,0 +1,18 @@
+# Playbook: Execution Phases Management
+
+Use this playbook when adding, modifying, or removing lifecycle phases in the AIUP governance pipeline (via `/clc add_phase`, `/clc remove_phase`, or conversational request like *"agregá una fase de smoke test antes del commit"*).
+
+## Guidelines
+
+1. **Understand Phase Purpose:**
+   - Pre-implementation (e.g. Research, SDD spec, RFC alignment)
+   - Implementation (e.g. TDD Red/Green, Layer Check)
+   - Verification / Audit (e.g. AST Audit, E2E, Smoke test)
+   - Delivery (e.g. Git pre-commit, PR generation)
+
+2. **Update `.clckernel.yaml`:**
+   - Preserve execution order and dependencies.
+   - Specify whether the phase is blocking (`required: true`) or advisory (`required: false`).
+
+3. **Confirm & Validate:**
+   - Present the updated pipeline flow to the user.

package/.agents/skills/clckernel_cli/reference/start.md

@@ -0,0 +1,28 @@
+# Playbook: Start / Initialize CLC Kernel
+
+Use this playbook when the user wants to initialize, start, or set up governance in a project (via `/clc start`, `/clckernel start`, or conversational request like *"inicializar el proyecto con clc"*).
+
+## Sequence
+
+### Phase 1: Silent Discovery
+1. Inspect project root files without asking. Look for signatures:
+   - `package.json` -> Next.js / Astro / Node
+   - `requirements.txt` / `pyproject.toml` -> FastAPI / Django
+   - `go.mod` -> Go
+   - `Cargo.toml` -> Rust
+   - `Gemfile` -> Rails
+   - `composer.json` -> Laravel
+   - `Dockerfile`, `docker-compose.yml`, `redis.conf`, `celery.py` -> Secondary tech stack
+2. **Rule:** Never guess the tech stack. Inspect the actual repository files.
+
+### Phase 2: Interactive Alignment
+Present detected stack and proposal clearly:
+1. Summarize detected architecture and auto-provisioned safeguards (e.g., TDD Red/Green, AST architecture guard, DB efficiency, secrets scan, tech-specific guards).
+2. Ask one clear question:
+   - *"¿Activamos estas fases y salvaguardas estándar, o querés personalizar alguna regla o fase?"*
+3. **STOP.** Wait for the user's response.
+
+### Phase 3: Materialization
+1. Write or update `.clckernel.yaml` at project root.
+2. If hooks are configured, ensure `.githooks/pre-commit` or `.husky/pre-commit` are provisioned.
+3. Confirm completion with a concise summary.

package/.agents/skills/clckernel_cli/reference/test.md

@@ -0,0 +1,22 @@
+# 🧪 Playbook: \`clckernel test\`
+
+Execute the repository test suite within the native environment runner.
+
+## Mandatory Execution Protocol
+
+### Step 1: Detect Test Runner
+1. Inspect \`.clckernel.yaml\` or project files to identify the configured test runner:
+   - Node: \`npm test\` / \`vitest\` / \`jest\`
+   - Python: \`pytest\`
+   - Go: \`go test ./...\`
+   - Ruby: \`bundle exec rspec\`
+   - Rust: \`cargo test\`
+   - PHP: \`vendor/bin/pest\` / \`phpunit\`
+
+### Step 2: Run Tests
+1. Execute the test command.
+2. If tests fail:
+   - Provide clear failure tracebacks.
+   - Propose fixing through the \`clckernel fix\` protocol.
+3. If tests pass:
+   - Confirm green test status (exit code 0).

package/.agents/skills/clckernel_cli/reference/update.md

@@ -0,0 +1,33 @@
+# Playbook: Update / Upgrade CLC Kernel
+
+Use this playbook when the user wants to update an existing project to the latest version of CLC Kernel (via `/clc update`, `clckernel update`, `npx clckernel update`, or conversational request like *"actualizar clckernel en el proyecto"*).
+
+## Invariants: The Non-Destructive Update Contract
+
+1. **NEVER DELETE OR OVERWRITE `sdds/`:** All local specifications (`sdds/*/spec.md`, `plan.md`) must stay 100% intact.
+2. **NEVER TOUCH CUSTOM GUARDS:** Any user-defined scripts under `tools/guards/` are preserved without alteration.
+3. **NEVER OVERWRITE CONFIGURATION:** Existing `.clckernel.yaml` or `.clc-forge.yaml` settings and custom thresholds remain intact.
+4. **NEVER MODIFY APPLICATION CODE:** Source files, domain layers, and application tests are never touched.
+
+## Update Sequence
+
+### Phase 1: Inspection & Detection
+1. Verify the project is already governed by checking for `AGENTS.md`, `.clckernel.yaml`, `.husky/pre-commit`, or `.githooks/pre-commit`.
+2. Inspect the active framework and test runner.
+
+### Phase 2: Refresh Core Infrastructure
+1. Refresh bundled AST audit tools in `tools/`:
+   - `tools/audit.js` / `tools/audit.py`
+   - Built-in guards (`scan_secrets.js`, `check_responsive.js`, `check_seo.js`, `check_db_efficiency.py`, `check_custom.js`, `docker_guard.py`, etc.)
+2. Refresh Agent Skills & Playbooks:
+   - Synchronize `.agents/skills/clckernel_cli/` with latest playbooks and references.
+3. Refresh Cross-IDE Rule Symlinks:
+   - Ensure `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, and `.antigravity/rules.md` link to `AGENTS.md`.
+4. Refresh Pre-commit Hook:
+   - Ensure the git pre-commit hook runs the latest standard guards while preserving any custom checks.
+
+### Phase 3: Verification & Reporting
+1. Run `node tools/audit.js` or `python tools/audit.py` to verify harness health.
+2. Output a transparent Educational Summary highlighting:
+   - What was updated (core tools, playbooks, symlinks)
+   - What was preserved (SDDs, custom guards, YAML configuration)

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "clckernel",
-  "version": "1.2.12",
+  "version": "1.2.17",
   "description": "CLC Kernel — The Universal Polyglot AI Agent Governance Engine (Next.js, FastAPI, Django, Astro, Rails, Go, Rust, Laravel).",
   "main": "./bin/cli.js",
   "files": [
     "bin",
     "src",
     "tools",
+    ".agents/skills/clckernel_cli",
     "README.md",
     "README.es.md"
   ],

package/src/adapters/agent-os.js

@@ -76,36 +76,36 @@ class AgentOSAdapter extends BaseAdapter {
     return [
       {
         name: 'check_symlinks',
-        language: 'node',
-        path: 'tools/check_symlinks.js',
+        language: 'js',
+        path: 'check_symlinks.js',
         command: 'node tools/check_symlinks.js',
         description: 'AI IDE symlinks and rule mirror verification'
       },
       {
         name: 'check_hitl',
-        language: 'node',
-        path: 'tools/check_hitl.js',
+        language: 'js',
+        path: 'check_hitl.js',
         command: 'node tools/check_hitl.js',
         description: 'Human-in-the-Loop review checkpoint validator'
       },
       {
         name: 'check_domain_data',
-        language: 'node',
-        path: 'tools/check_domain_data.js',
+        language: 'js',
+        path: 'check_domain_data.js',
         command: 'node tools/check_domain_data.js',
         description: 'Domain deliverables schema and clean state integrity'
       },
       {
         name: 'check_test_calendar_sync',
-        language: 'node',
-        path: 'tools/check_test_calendar_sync.js',
+        language: 'js',
+        path: 'check_test_calendar_sync.js',
         command: 'node tools/check_test_calendar_sync.js',
         description: 'Test calendar harness synchronization and parity check'
       },
       {
         name: 'scan_secrets',
-        language: 'node',
-        path: 'tools/scan_secrets.js',
+        language: 'js',
+        path: 'scan_secrets.js',
         command: 'node tools/scan_secrets.js',
         description: 'Security & API key leak scanner'
       }
@@ -198,7 +198,7 @@ ${this.getSafeguards().map(s => `- ${s}`).join('\n')}
     // 4. Copy domain guard tools into tools/
     const srcToolsDir = path.join(__dirname, '..', '..', 'tools');
     const targetToolsDir = path.join(targetDir, 'tools');
-    const toolsToCopy = ['check_symlinks.js', 'check_hitl.js', 'check_domain_data.js', 'scan_secrets.js', 'audit.js'];
+    const toolsToCopy = ['check_symlinks.js', 'check_hitl.js', 'check_domain_data.js', 'check_test_calendar_sync.js', 'scan_secrets.js', 'audit.js'];
 
     for (const toolFile of toolsToCopy) {
       const srcFile = path.join(srcToolsDir, toolFile);

package/src/catalog.js

@@ -125,6 +125,11 @@ const SAFEGUARD_CATALOG = [
     applies_when: 'agent-os', severity: 'error', gate_mode: 'hard', config_keys: ['scope'],
     phase: 'audit', file: 'check_domain_data.js', manifest: true, planned: false },
 
+  { 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 },
+
   { name: 'ruff', labels: ['ruff'],
     checks: 'Python AST linter (external CLI)', verify: ['verify_python_lint'],
     applies_when: 'backend', severity: 'warning', gate_mode: 'advisory', config_keys: [],

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

package/tools/check_custom.js

@@ -7,7 +7,7 @@
  * @param {string} targetDir - Directory to scan (defaults to cwd)
  * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
  */
-const { parseYaml, globToRegex } = require('../src/yaml.js');
+const { parseYaml, globToRegex } = require('./yaml.js');
 const check = async function checkCustom(targetDir) {
   const fs = require('fs');
   const path = require('path');

package/tools/check_hitl.js

@@ -22,10 +22,22 @@ const check = async function checkHitl(targetDir) {
   for (const sDir of searchDirs) {
     if (fs.existsSync(sDir)) {
       try {
-        const files = fs.readdirSync(sDir);
-        for (const file of files) {
-          if (file.endsWith('.md')) {
-            skillFiles.push(path.join(sDir, file));
+        const entries = fs.readdirSync(sDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isFile() && entry.name.endsWith('.md')) {
+            skillFiles.push(path.join(sDir, entry.name));
+          } else if (entry.isDirectory()) {
+            // Exclude framework CLI scaffolding and tool plugins
+            if (entry.name === 'clckernel_cli' || entry.name === 'clc_forge_cli' || entry.name === 'impeccable') {
+              continue;
+            }
+            const subDirPath = path.join(sDir, entry.name);
+            const subEntries = fs.readdirSync(subDirPath, { withFileTypes: true });
+            for (const sub of subEntries) {
+              if (sub.isFile() && sub.name.endsWith('.md')) {
+                skillFiles.push(path.join(subDirPath, sub.name));
+              }
+            }
           }
         }
       } catch {}