clckernel 1.2.6 → 1.2.9

package/README.es.md

@@ -1,6 +1,5 @@
 <div align="center">
-  <img width="350" height="350" alt="clckernel_logo" src="https://github.com/user-attachments/assets/2898e9c1-ec7a-4c60-a6dd-e62c05a0d446" />
-</div>
+  <img width="280" height="280" alt="clckernel_logo" src="https://github.com/user-attachments/assets/2898e9c1-ec7a-4c60-a6dd-e62c05a0d446" />
 
 # 🤖 CLC Kernel (`clckernel`)
 
@@ -8,30 +7,41 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![English](https://img.shields.io/badge/README-English-blue.svg)](./README.md)
 
-> **El Motor Universal de Gobernanza para Agentes de IA & Orquestador AIUP.**
-> Creado por [CarlosLeonCode](https://github.com/carlosleoncode).
+**El Motor Universal de Gobernanza Determinista para Agentes de IA & Orquestador AIUP.**
+*Creado por [CarlosLeonCode](https://github.com/carlosleoncode).*
+</div>
 
-Los agentes de IA (Claude, Cursor, Gemini, Copilot) generan código a una velocidad sin precedentes. Sin embargo, sin límites estrictos introducen degradación arquitectónica, tests de falso positivo y deuda técnica invisible. **CLC Kernel** es el arnés de desarrollo definitivo para gobernarlos.
+Los agentes de programación con IA (Cursor, Claude Code, Windsurf, Copilot) codifican a gran velocidad, pero sin límites introducen degradación arquitectónica, tests falsos positivos y fuga de credenciales.
 
-Establece un **Proceso Unificado de IA (AIUP)**—obligando a los LLMs a operar como ingenieros de software disciplinados en cualquier lenguaje de programación (Next.js, FastAPI, Django, Astro, Rails, Go, Rust, Laravel).
+**CLC Kernel** es un arnés de desarrollo políglota que gobierna físicamente a los agentes mediante **linters AST deterministas (< 5ms)**, **especificaciones SDD locales** y el cumplimiento del **Proceso Unificado de IA (AIUP)**.
 
 ---
 
-## 🎯 1. Posicionamiento: Una Nueva Categoría — AI Agent Governance
+## 📋 Tabla de Contenidos
+- [🎯 Casos de Uso](#-casos-de-uso)
+- [🏛️ El Proceso Unificado de IA (AIUP)](#️-el-proceso-unificado-de-ia-aiup)
+- [⚡ Guía Paso a Paso (Ciclo Completo)](#-guía-paso-a-paso-ciclo-completo)
+- [🎮 Interfaz Universal de Comandos](#-interfaz-universal-de-comandos)
+- [🌐 Ecosistemas Soportados y Arquetipos](#-ecosistemas-soportados-y-arquetipos)
+- [🧩 Herramientas Complementarias (Opcionales)](#-herramientas-complementarias-opcionales)
+- [📄 Licencia](#-licencia)
 
-CLC Kernel **no** es "otro framework de IA" ni una colección de prompts. Define una categoría de ingeniería propia: **Gobernanza Determinística de Agentes de IA (AI Agent Governance)**.
+---
 
-| Categoría de Herramienta | Qué Hace | Dónde se Queda Corta | Ventaja de CLC Kernel |
-|---|---|---|---|
-| **Reglas de Prompt** (`.cursorrules`, `.mdc`) | Inyecta sugerencias en markdown en el contexto del chat. | **No determinístico:** El LLM las ignora en contextos largos o pedidos rápidos. | Impone **AST Linters nativos** que bloquean físicamente commits no conformes. |
-| **Herramientas de Specs** (OpenSpec, Specs en MD) | Documenta especificaciones y requerimientos. | **Estático:** No comprueba tests fallidos ni custodia cambios de código en Git. | Ciclo completo **AIUP:** Spec -> Gate Humano -> TDD Rojo-a-Verde -> AST Guard. |
-| **Runtimes de Agentes** (LangGraph, CrewAI) | Construye apps de backend con agentes autónomos. | **Problema distinto:** No gobierna el desarrollo en el repositorio del programador. | **Arnés para Devs:** Se integra nativamente en el flujo diario de tu IDE. |
+<a id="casos-de-uso"></a>
+## 🎯 Casos de Uso
 
----
+| Caso de Uso | Problema que Resuelve | Cómo lo Resuelve CLC Kernel |
+|---|---|---|
+| **1. Gobernanza de Coding Agents**<br>*(Cursor, Claude Code, Copilot)* | Los agentes programan por intuición ("vibe coding"), se saltan pruebas y rompen capas de arquitectura en backend y frontend. | Impone la **Regla #0** (Investigación -> SDD -> TDD Rojo a Verde -> Auditoría AST) y bloquea commits no conformes mediante linters AST. |
+| **2. Arquetipos Agent-OS y Flujos de Dominio**<br>*(Bots autónomos, OS de marketing/ventas)* | Runtimes de agentes ejecutan acciones sin supervisión, alucinan métricas o desincronizan reglas en diferentes IDEs. | Provee **Gobernanza Dual-Layer**, valida symlinks de reglas para IDEs, exige compuertas Human-in-the-Loop (`check_hitl`) y valida esquemas con null seguro (`check_domain_data`). |
+| **3. Refactorizaciones y Migraciones Críticas** | Los agentes modifican archivos fuera del alcance acordado, introduciendo regresiones silenciosas. | Delimita el trabajo en una especificación local `sdds/{cambio}/spec.md` y bloquea commits que toquen archivos no autorizados (`check_scope`). |
+| **4. Blindaje Pre-Commit y Shift-Left en CI/CD** | Fuga de credenciales, consultas N+1 en bucles y migraciones destructivas llegan a ramas remotas. | Ejecuta validaciones AST sin dependencias foráneas en el lenguaje nativo del stack en **< 5ms** antes de cada commit. |
 
-## 🏛️ 2. Pilares Conceptuales del Ecosistema
+---
 
-CLC Kernel se apoya en cinco fundamentos de ingeniería diseñados para erradicar los vicios del "Vibe Coding":
+<a id="aiup"></a>
+## 🏛️ El Proceso Unificado de IA (AIUP)
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
@@ -43,91 +53,16 @@ CLC Kernel se apoya en cinco fundamentos de ingeniería diseñados para erradica
 └─────────────┴─────────────┴─────────────┴──────────────────┴────────────────┘
 ```
 
-### 📝 A. Spec-Driven Development (SDD)
-Los agentes sufren del *sesgo de inmediatez*—escribir código antes de entender los requerimientos. CLC Kernel prohíbe la modificación directa: el agente debe primero redactar una especificación técnica local (gitignorada en `sdds/{feature-name}/`) detallando objetivos, capas afectadas y casos borde.
-
-### 🛑 B. Human-in-the-Loop Gate (HIT)
-Antes de tocar una sola línea de código en producción, el agente debe presentar escenarios de prueba concretos al desarrollador para su validación y aprobación. **El humano es el Arquitecto/Director; la IA es el Ejecutor.**
-
-### 🧪 C. Test-Driven Development (TDD Rojo-a-Verde)
-Los agentes suelen generar "tests tautológicos" que nunca fallan ante bugs reales. CLC Kernel impone TDD genuino: el agente debe escribir un test de regresión que falle primero (Fase Roja) y demostrar el fallo antes de escribir la implementación (Fase Verde).
-
-### 🛡️ D. Salvaguardas AST Determinísticas (Linters Nativos)
-Las instrucciones en markdown se olvidan con facilidad. CLC Kernel provisiona linters basados en el Árbol de Sintaxis Abstracta (AST) en el lenguaje nativo del stack (Python `ast`, Go `ast`, RuboCop, PHPStan, TypeScript AST). Estos guardias validan físicamente los cambios y bloquean commits inválidos:
-- **📱 Frontend & UX:** Breakpoints mobile-first y touch targets de 44px (`check_responsive`), metadata SEO/tags GEO/prioridad LCP (`check_seo`), accesibilidad ARIA (`check_a11y`), reutilización de primitivas UI (`check_ui_reuse`), optimización de imágenes y tree-shaking (`check_performance`), y contratos Zod (`check_api_contracts`).
-- **🏛️ Backend & Arquitectura:** Aislamiento de capas Clean Architecture (`check_architecture`), prevención de queries N+1 en loops (`check_db_efficiency`), idempotencia de migraciones (`check_migrations`), y escaneo de secretos (`scan_secrets`).
-- **🎯 Proceso & Infraestructura:** Validación de alcance git diff vs SDD (`check_scope`), prueba de transición TDD Rojo-a-Verde (`verify_tdd`), y guardias de tecnologías (`docker_guard`, `celery_guard`, `redis_guard`, `postgres_guard`).
-
-### 🔗 E. Single Source of Truth (SSOT) & Espejado Dinámico (Mirroring)
-Mantener archivos de reglas separados para Cursor, Claude, Windsurf, Copilot y Gemini produce desincronización y deriva de contexto. CLC Kernel lo resuelve mediante **Espejado Dinámico**:
-- `AGENTS.md` se forja como el **Single Source of Truth** (Única Fuente de Verdad).
-- Symlinks multiplataforma proyectan automáticamente `AGENTS.md` hacia:
-  - 🧠 `CLAUDE.md` (Claude Desktop / Windsurf)
-  - 🌌 `GEMINI.md` (Gemini CLI / Project IDX)
-  - 💠 `.cursorrules` & `.cursor/rules/clckernel_context.mdc` (Cursor)
-  - ✈️ `.github/copilot-instructions.md` (GitHub Copilot)
-  - 🛸 `.antigravity/rules.md` (Antigravity)
-- *Editás una sola vez en `AGENTS.md` y todos los IDEs absorben el contexto de forma instantánea y con cero duplicación.*
-
----
-
-## 💡 3. Por Qué Existe CLC Kernel
-
-Librados a su suerte, los agentes de IA generan **Deuda de Comprensión (Comprehension Debt)**—un código que crece más rápido que la capacidad del equipo de mantener su arquitectura:
-
-<div align="center">
-  <img width="900" alt="clckernel_comparison_es" src="https://github.com/user-attachments/assets/4d2e6651-15be-46f6-ae12-c8274b6492ca" />
-  <p><em>Izquierda: Agente de IA sin gobernanza — código caótico y alucinado. Derecha: Agente con CLC Kernel AIUP — estructurado, seguro y arquitectónicamente correcto.</em></p>
-</div>
-
-- ❌ **Decaimiento Arquitectónico:** Mezclar lógica de rutas con llamadas a la base de datos en lugar de respetar el aislamiento de capas.
-- ❌ **Duplicación de UI:** Inventar colores hexadecimales arbitrarios y HTML crudo en lugar de reutilizar los tokens del sistema de diseño.
-- ❌ **Tests de Falso Positivo:** Declarar que una feature funciona sin jamás demostrar la transición Rojo-a-Verde.
-- ❌ **Fugas de Seguridad:** Commitear accidentalmente API Keys o exponer DTOs privados del backend al cliente.
-
----
-
-## 🧩 4. Dependencias Deseadas del Ecosistema (Opcionales y Modulares)
-
-CLC Kernel se enfoca estrictamente en **Gobernanza, Proceso y Salvaguardas de Calidad**. Intencionalmente **no** empaqueta un motor de grafos propietario ni una base de datos de persistencia monolítica. En su lugar, delega esas capacidades en herramientas complementarias especializadas (con degradación elegante si no se encuentran instaladas en el entorno):
-
-| Herramienta Complementaria | Rol | Por Qué es Deseada | Comportamiento si no está |
-|---|---|---|---|
-| 🧠 **[Engram (MCP)](https://github.com/Gentleman-Programming/gentle-ai)** | Memoria de Largo Plazo & ADRs | Preserva el contexto arquitectónico, justificaciones de diseño y memoria entre sesiones de agentes. | Salteo elegante (la auditoría continúa sin persistencia). |
-| 🕸️ **[Graphify](https://github.com/carlosleoncode/graphify)** | Grafo de Conocimiento de Código | Genera mapas topológicos y grafos de dependencias para que el agente entienda relaciones arquitectónicas. | Salteo elegante (`verify_memory_graph` pasa como advisory). |
-| 🛡️ **[Gentle AI (RDD)](https://github.com/Gentleman-Programming/gentle-ai)** | Gate de Revisión Adversaria | Aplica Review-Driven Development (RDD) con inspección multi-lente antes de commitear cambios. | Salteo elegante (`verify_rdd_review_gate` pasa como advisory). |
-| ⚡ **Linters Nativos por Stack** | AST & Seguridad de Tipos | `ruff` (Python), `golangci-lint` (Go), `cargo clippy` (Rust), `phpstan` (PHP), `tsc` (TypeScript). | Utiliza las herramientas CLI instaladas en el entorno local del proyecto. |
-
----
-
-## 🧠 5. El Paradigma de la CLI Conversacional
-
-CLC Kernel opera tanto en tu terminal como dentro del chat de tu IDE con IA. Al inicializarse, inyecta un **Agentic Playbook (`SKILL.md`)** en tu repositorio, convirtiendo cualquier LLM en un asistente interactivo de gobernanza:
-
-- 🚀 **`clckernel start`**: Detecta tu stack automáticamente, propone un ciclo de gobernanza, y materializa `.clckernel.yaml`.
-- 🛠️ **`clckernel create_guard`**: Escribe un linter AST personalizado en el lenguaje nativo de tu stack (`tools/guards/`).
-- 🔄 **`clckernel add_phase` / `remove_guard`**: Modifica el ciclo de vida AIUP interactivamente sin editar YAML manualmente.
+1. **SDD (Spec-Driven Development):** El agente debe redactar una especificación técnica local gitignorada (`sdds/{feature}/spec.md`) antes de tocar código de producción.
+2. **HIT (Human-in-the-Loop):** El ingeniero revisa y aprueba los contratos y escenarios de prueba antes del inicio de la implementación.
+3. **TDD (Rojo a Verde):** El agente debe demostrar un test de regresión fallido (Fase Roja) antes de escribir la solución en producción (Fase Verde).
+4. **AST (Salvaguardas Deterministas):** Parsers nativos del stack (Python `ast`, Go `ast`, RuboCop, TypeScript AST) inspeccionan el diff y bloquean físicamente commits no conformes.
+5. **SSOT (Única Fuente de Verdad):** `AGENTS.md` se define una sola vez y se proyecta mediante symlinks hacia `CLAUDE.md`, `GEMINI.md`, `.cursorrules` y Copilot.
 
 ---
 
-## 🌐 6. Adaptadores Polyglot por Stack
-
-CLC Kernel cuenta con adaptadores dedicados para los principales ecosistemas:
-
-| Ecosistema | Firma de Detección | Test Runner | Salvaguardas Aplicadas |
-|---|---|---|---|
-| ⚛️ **Next.js** | `next` | Vitest / Jest | Reutilización de UI, Tokens Semánticos, Reglas RSC, Zod, A11y, Responsive, SEO, Performance |
-| ⚡ **FastAPI** | `fastapi` | Pytest | Pydantic V2, Idempotencia Alembic, AST Arquitectura Limpia, Eficiencia DB (N+1) |
-| 💎 **Rails** | `Gemfile` | RSpec | AST RuboCop, Seguridad Brakeman, Idempotencia de Migraciones |
-| 🐹 **Golang** | `go.mod` | `go test` | AST `golangci-lint`, Arquitectura Domain/UseCase |
-| 🦀 **Rust** | `Cargo.toml` | `cargo test` | AST `cargo clippy`, `cargo audit`, Seguridad de Memoria Estricta |
-| 🐘 **Laravel** | `artisan` | Pest / PHPUnit | AST PHPStan, Detección de N+1 Eloquent, Migraciones |
-| 🎸 **Django** | `manage.py` | `pytest-django` | Idempotencia ORM Django, AST Ruff, Scope Guard, Eficiencia DB (N+1) |
-| 🚀 **Astro** | `astro.config` | Playwright | Tokens Tailwind v4, Content Collection Schema, A11y, Responsive, SEO |
-
----
-
-## ⚡ 7. Guía Paso a Paso (Ciclo de Vida Completo)
+<a id="guia-paso-a-paso"></a>
+## ⚡ Guía Paso a Paso (Ciclo Completo)
 
 ```
 [1. Terminal]           [2. Chat del LLM]            [3. Bucle TDD]                [4. Git Commit]
@@ -137,30 +72,88 @@ npx clckernel   ───►   clckernel start   ───►   "Feature X con h
 
 ### 1️⃣ Paso 1: Inicializar el Repositorio (Terminal)
 ```bash
-npx clckernel
+npx clckernel start
 ```
-Detecta tu framework, genera `AGENTS.md`, crea symlinks dinámicos para todos los IDEs, provisiona hooks pre-commit (`.husky/` o `.githooks/`) y crea herramientas AST en `tools/`.
+Detecta el framework, genera `AGENTS.md`, crea symlinks dinámicos para todos los IDEs (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`), provisiona hooks pre-commit e instala verificadores AST en `tools/`.
 
-### 2️⃣ Paso 2: Abrir tu IDE con IA e Inicializar (CLI Conversacional)
+### 2️⃣ Paso 2: Inicializar en el Chat del IDE (CLI Conversacional)
 Abrí Cursor, Claude Code, Gemini CLI, Windsurf o Copilot y escribí:
 > `clckernel start`
-El agente escanea tu código en silencio, propone un plan de gobernanza AIUP adaptado a tu stack y genera `.clckernel.yaml`.
 
-### 3️⃣ Paso 3: Desarrollar con el Arnés AIUP
-Al pedir una funcionalidad o corrección, activá el workflow:
-> *"Agregá el endpoint de autenticación. **Usá el workflow / harness**."*
-El agente ejecuta de forma autónoma el ciclo de 10 pasos: **SDD Spec -> Gate HIT -> TDD Rojo-a-Verde -> Implementación Limpia -> Auditoría AST**.
+El agente escanea tu código en silencio, propone un plan de gobernanza adaptado a tu stack y genera `.clckernel.yaml`.
 
-### 4️⃣ Paso 4: Verificación Determinística de Guards (Commit)
+### 3️⃣ Paso 3: Desarrollar con el Arnés AIUP
+Al solicitar una funcionalidad o corrección, indicá al agente:
+> *"Implementa el endpoint de autenticación. **Usa el harness de CLC Kernel**."*
+
+El agente ejecutará de forma autónoma el ciclo AIUP completo:
+1. **Investigación y Causa Raíz:** Inspecciona el código base y dependencias.
+2. **Especificación SDD Local:** Redacta contratos de API y planes de prueba en `sdds/{cambio}/spec.md`.
+3. **Revisión HIT:** Solicita tu revisión y aprobación de los contratos propuestos.
+4. **Fase Roja TDD:** Escribe un test de regresión que falle demostrando el requerimiento.
+5. **Implementación Verde:** Escribe el código mínimo necesario respetando el aislamiento de capas.
+6. **Compuerta de Auditoría AST:** Ejecuta `node tools/audit.js` y emite el resumen de verificación.
+
+### 4️⃣ Paso 4: Verificación Determinística de Guards (Git Commit)
 ```bash
 git add .
 git commit -m "feat(auth): add user authentication endpoint"
 ```
-Los hooks pre-commit ejecutan escáneres AST automáticos (Clean Architecture, Fuga de Secretos, Scope Guard, Idempotencia de Migraciones). Cualquier violación bloquea el commit de inmediato.
+Los hooks pre-commit ejecutan automáticamente los escáneres AST (Clean Architecture, Fuga de Secretos, Scope Guard, Idempotencia de Migraciones). Cualquier violación **bloquea físicamente** el commit.
 
-### 5️⃣ Paso 5: Auditar la Salud del Repositorio en Cualquier Momento (Terminal)
+### 5️⃣ Paso 5: Auditar la Salud del Repositorio en Cualquier Momento (Doctor)
 ```bash
 npx clckernel doctor
 ```
-Ejecuta el **CLC Kernel Doctor** para verificar el 100% de cumplimiento en `AGENTS.md`, `sdds/`, `tools/` y hooks de Git.
+Audita el 100% de cumplimiento en `AGENTS.md`, `sdds/`, `tools/`, runners de pruebas activos y hooks de Git.
+
+---
+
+<a id="interfaz-universal-de-comandos"></a>
+## 🎮 Interfaz Universal de Comandos (Todos los LLMs y Agentes)
+
+CLC Kernel provee una gramática de comandos determinista soportada de forma nativa por **Claude Code, Cursor, Codeium/Windsurf, Copilot, Gemini y Antigravity**:
+
+| Comando | Categoría | Protocolo de Ejecución Obligatorio |
+|---|---|---|
+| `clckernel feature <nombre>` | Funcionalidad | Ciclo AIUP completo: Investigación -> Spec Local (`sdds/{nombre}/spec.md`) -> Revisión HIT -> Fase Roja TDD -> Implementación Verde -> Auditoría. |
+| `clckernel fix <descripción>` | Corrección | Análisis de causa raíz (sin editar código) -> Test de regresión que falle -> Corrección quirúrgica limpia -> Compuerta de auditoría. |
+| `clckernel test` | Verificación | Ejecuta la suite de pruebas en el runner nativo del stack y confirma estado verde limpio. |
+| `clckernel audit` | Verificación | Ejecuta `node tools/audit.js` o `python tools/audit.py` y emite el Resumen Educativo. |
+| `clckernel doctor` | Diagnóstico | Valida hooks pre-commit de Git, symlinks espejo para IDEs e integridad del motor AST. |
+| `clckernel commit <mensaje>` | Control de Versiones | Auditoría pre-flight, verificación de scope diff vs SDD y commit con Conventional Commits (cero atribución de IA). |
+| `clckernel guard create <nombre>` | Salvaguardas | Genera el scaffold de un nuevo script de guard AST en el lenguaje nativo del stack en `tools/guards/`. |
+| `clckernel start` | Configuración | Detecta el stack automáticamente, propone el ciclo de vida AIUP y genera `.clckernel.yaml`. |
+
+---
+
+<a id="ecosistemas-soportados"></a>
+## 🌐 Ecosistemas Soportados y Arquetipos
+
+| Ecosistema | Firma de Detección | Test Runner | Salvaguardas Nativas |
+|---|---|---|---|
+| ⚛️ **Next.js** | `next` | Vitest / Jest | Clean Architecture, Reutilización de UI, Tokens Semánticos, RSC, A11y, Responsive, SEO |
+| ⚡ **FastAPI** | `fastapi` | Pytest | Pydantic V2, Idempotencia Alembic, AST Clean Architecture, Eficiencia DB (N+1) |
+| 💎 **Rails** | `Gemfile` | RSpec | AST RuboCop, Seguridad Brakeman, Idempotencia de Migraciones |
+| 🐹 **Golang** | `go.mod` | `go test` | AST `golangci-lint`, Aislamiento de Capas Dominio/Casos de Uso |
+| 🦀 **Rust** | `Cargo.toml` | `cargo test` | AST `cargo clippy`, `cargo audit`, Seguridad Estricta de Memoria |
+| 🐘 **Laravel** | `artisan` | Pest / PHPUnit | AST PHPStan, Detección de Consultas N+1 en Eloquent, Migraciones |
+| 🎸 **Django** | `manage.py` | `pytest-django` | Idempotencia ORM Django, AST Ruff, Scope Guard, Eficiencia DB (N+1) |
+| 🚀 **Astro** | `astro.config` | Playwright | Tokens Tailwind v4, Esquemas de Colección, A11y, Responsive, SEO |
+| 🤖 **Agent-OS** | `skills/`, `brand/`, `templates/` | Tests de Contrato | AGENTS.md Dual-Layer, Compuertas HITL (`check_hitl`), Symlinks (`check_symlinks`), Integridad de Datos (`check_domain_data`) |
+
+---
+
+<a id="herramientas-complementarias"></a>
+## 🧩 Herramientas Complementarias (Opcionales)
+
+CLC Kernel se enfoca estrictamente en gobernanza y opera con **cero dependencias foráneas**. Se integra de forma modular con:
+- 🧠 **[Engram (MCP)](https://github.com/Gentleman-Programming/gentle-ai):** Memoria arquitectónica persistente y registro de ADRs entre sesiones.
+- 🕸️ **[Graphify](https://github.com/carlosleoncode/graphify):** Generación de grafos visuales de dependencias y topología del código.
+- 🛡️ **[Gentle AI (RDD)](https://github.com/Gentleman-Programming/gentle-ai):** Compuerta de revisión multi-lente adversaria antes de commitear.
+
+---
 
+<a id="licencia"></a>
+## 📄 Licencia
+MIT © [CarlosLeonCode](https://github.com/carlosleoncode)

package/README.md

@@ -1,6 +1,5 @@
 <div align="center">
-  <img width="350" height="350" alt="clckernel_logo" src="https://github.com/user-attachments/assets/ed631ce1-c996-4347-b818-97b8ab25e0ec" />
-</div>
+  <img width="280" height="280" alt="clckernel_logo" src="https://github.com/user-attachments/assets/ed631ce1-c996-4347-b818-97b8ab25e0ec" />
 
 # 🤖 CLC Kernel (`clckernel`)
 
@@ -8,30 +7,41 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Español](https://img.shields.io/badge/README-Español-blue.svg)](./README.es.md)
 
-> **The Universal Polyglot AI Agent Governance Engine & AIUP Orchestrator.**
-> Built by [CarlosLeonCode](https://github.com/carlosleoncode).
+**Deterministic AI Agent Governance Engine & AIUP Orchestrator.**
+*Forged by [CarlosLeonCode](https://github.com/carlosleoncode).*
+</div>
 
-AI coding agents (Claude, Cursor, Gemini, Copilot) generate code at unprecedented speeds. However, without strict boundaries, they introduce architectural decay, false-positive tests, and invisible technical debt. **CLC Kernel** is the definitive developer harness to govern them.
+AI coding agents (Cursor, Claude Code, Windsurf, Copilot) code fast, but without guardrails they create architectural decay, tautological tests, and secret leaks. 
 
-It establishes an **AI Unified Process (AIUP)**—forcing LLMs to operate like disciplined software engineers across any programming language (Next.js, FastAPI, Django, Astro, Rails, Go, Rust, Laravel).
+**CLC Kernel** is a polyglot developer harness that physically governs AI agents using **deterministic AST linters (< 5ms)**, **local SDD specs**, and an enforced **AI Unified Process (AIUP)**.
 
 ---
 
-## 🎯 1. Positioning: A New Category — AI Agent Governance
+## 📋 Table of Contents
+- [🎯 Use Cases](#-use-cases)
+- [🏛️ The AI Unified Process (AIUP)](#️-the-ai-unified-process-aiup)
+- [⚡ Step-by-Step Guide (Full Lifecycle)](#-step-by-step-guide-full-lifecycle)
+- [🎮 Universal Command Interface](#-universal-command-interface)
+- [🌐 Supported Stacks & Archetypes](#-supported-stacks--archetypes)
+- [🧩 Optional Ecosystem Companions](#-optional-ecosystem-companions)
+- [📄 License](#-license)
 
-CLC Kernel is **not** "just another AI framework" or prompt collection. It pioneers a distinct engineering category: **Deterministic AI Agent Governance**.
+---
 
-| Tool Category | What It Does | Where It Falls Short | CLC Kernel Advantage |
-|---|---|---|---|
-| **Prompt Rules** (`.cursorrules`, `.mdc`) | Injects markdown suggestions into chat context. | **Non-deterministic:** Ignored during large contexts or quick-fix prompts. | Enforces native **AST Linters** that physically block non-compliant Git commits. |
-| **Spec Tools** (OpenSpec, Markdown specs) | Documents specifications & design requirements. | **Static:** Doesn't verify failing test transitions or guard code changes. | Full **AIUP lifecycle:** Spec -> Human Gate -> Red-to-Green TDD -> AST Verification. |
-| **Agent Runtimes** (LangGraph, CrewAI) | Builds multi-agent production backend apps. | **Different problem:** Doesn't govern human-in-the-loop repo development. | **Developer Tooling Harness:** Injected directly into your daily IDE workflow. |
+<a id="use-cases"></a>
+## 🎯 Use Cases
 
----
+| Use Case | Problem It Solves | How CLC Kernel Solves It |
+|---|---|---|
+| **1. Coding Agent Governance**<br>*(Cursor, Claude Code, Copilot)* | Agents "vibe code", bypass tests, and violate layer boundaries in backend/frontend apps. | Enforces **Rule #0** (Research -> SDD -> TDD Red-to-Green -> AST Audit) and blocks commits via native AST guards. |
+| **2. Agent-OS & Domain Workflows**<br>*(Autonomous bots, marketing/sales OS)* | Agent runtimes execute actions without review, hallucinate metrics, or drift across IDE configs. | Provides **Dual-Layer Governance**, validates IDE mirror symlinks, checks Human-in-the-Loop (`check_hitl`), and enforces null-safe schemas (`check_domain_data`). |
+| **3. Complex Refactors & Migrations** | Agents modify files outside the agreed feature scope, causing silent regressions. | Locks work to a local `sdds/{change}/spec.md` and fails commits modifying untouched layers (`check_scope`). |
+| **4. Shift-Left CI/CD & Pre-commit** | Secret leaks, N+1 query loops, and broken database migrations reach remote branches. | Runs zero-dependency AST checks in your stack's native language in **< 5ms** before Git commit. |
 
-## 🏛️ 2. Core Conceptual Pillars
+---
 
-CLC Kernel is built upon five foundational engineering principles designed to eliminate "vibe coding" hazards:
+<a id="aiup"></a>
+## 🏛️ The AI Unified Process (AIUP)
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
@@ -43,91 +53,16 @@ CLC Kernel is built upon five foundational engineering principles designed to el
 └─────────────┴─────────────┴─────────────┴──────────────────┴────────────────┘
 ```
 
-### 📝 A. Spec-Driven Development (SDD)
-Agents suffer from *immediacy bias*—writing code before understanding requirements. CLC Kernel forbids direct modifications: agents must first author a local, gitignored specification under `sdds/{feature-name}/` detailing objectives, architectural layer impacts, and edge cases.
-
-### 🛑 B. Human-in-the-Loop Gate (HIT)
-Before touching a single line of production code, the agent must present concrete test scenarios to the developer for review and approval. **The human is the Architect/Director; the AI is the Executor.**
-
-### 🧪 C. Test-Driven Development (TDD Red-to-Green)
-AI agents frequently generate "tautological tests" that never fail against bugs. CLC Kernel enforces real TDD: the agent must produce a failing regression test (Red Phase) and prove failure before writing implementation code (Green Phase).
-
-### 🛡️ D. Deterministic AST Safeguards (Native Code Linters)
-Markdown instructions can be forgotten by LLMs. CLC Kernel provisions deterministic Abstract Syntax Tree (AST) linters in the stack's native language (Python `ast`, Go `ast`, RuboCop, PHPStan, TypeScript AST). These guards physically validate code changes and block non-compliant commits:
-- **📱 Frontend & UX:** Mobile-first responsive breakpoints & 44px touch targets (`check_responsive`), SEO metadata/GEO tags/LCP priority (`check_seo`), ARIA accessibility (`check_a11y`), UI primitive reuse (`check_ui_reuse`), image optimization & tree-shaking (`check_performance`), and Zod API contracts (`check_api_contracts`).
-- **🏛️ Backend & Architecture:** Clean Architecture layer boundaries (`check_architecture`), N+1 query loop prevention (`check_db_efficiency`), migration idempotency (`check_migrations`), and secret leak scanning (`scan_secrets`).
-- **🎯 Process & Infrastructure:** Git diff vs SDD scope validation (`check_scope`), TDD Red-to-Green transition proof (`verify_tdd`), and tech guards (`docker_guard`, `celery_guard`, `redis_guard`, `postgres_guard`).
-
-### 🔗 E. Single Source of Truth (SSOT) & Dynamic Mirroring
-Managing separate instructions for Cursor, Claude, Windsurf, Copilot, and Gemini causes documentation drift. CLC Kernel solves this via **Dynamic Mirroring**:
-- `AGENTS.md` is forged as the **Single Source of Truth**.
-- Cross-platform filesystem symlinks automatically project `AGENTS.md` to:
-  - 🧠 `CLAUDE.md` (Claude Desktop / Windsurf)
-  - 🌌 `GEMINI.md` (Gemini CLI / Project IDX)
-  - 💠 `.cursorrules` & `.cursor/rules/clckernel_context.mdc` (Cursor)
-  - ✈️ `.github/copilot-instructions.md` (GitHub Copilot)
-  - 🛸 `.antigravity/rules.md` (Antigravity)
-- *Edit once in `AGENTS.md`, and all AI IDEs synchronize instantly with zero redundancy.*
-
----
-
-## 💡 3. Why CLC Kernel Exists
-
-Left unguided, AI agents create compounding **Comprehension Debt**—a codebase that grows faster than the team's ability to maintain its architecture:
-
-<div align="center">
-  <img width="900" alt="clckernel_comparison" src="https://github.com/user-attachments/assets/cb62753a-3e88-432d-9196-94eaa817864d" />
-  <p><em>Left: AI agent without governance — chaotic, hallucinated code. Right: AI agent with CLC Kernel AIUP — structured, safe, architectural.</em></p>
-</div>
-
-- ❌ **Architectural Decay:** Mixing routing logic with database queries instead of respecting layer isolation.
-- ❌ **UI Duplication:** Inventing raw HTML and arbitrary hex colors instead of reusing design tokens.
-- ❌ **False-Positive Tests:** Writing mocks that pass trivially without testing domain invariants.
-- ❌ **Secret Leaks:** Accidental commits of API credentials or private backend DTOs.
-
----
-
-## 🧩 4. Recommended Ecosystem Dependencies (Modular & Optional)
-
-CLC Kernel focuses strictly on **Governance, Process & Quality Guardrails**. It intentionally does not bundle monolithic databases or runtime graphs. Instead, it integrates modularly with companion tools (with graceful skip if absent):
-
-| Companion Tool | Role | Why It's Recommended | Fallback Behavior |
-|---|---|---|---|
-| 🧠 **[Engram (MCP)](https://github.com/Gentleman-Programming/gentle-ai)** | Long-Term Memory & ADRs | Preserves architectural context, design rationales, and cross-session knowledge for agents. | Graceful skip (audits proceed without persistent memory). |
-| 🕸️ **[Graphify](https://github.com/carlosleoncode/graphify)** | Code Knowledge Graph | Generates dependency graphs and visual codebase topology for architecture-aware agents. | Graceful skip (`verify_memory_graph` advisory check passes). |
-| 🛡️ **[Gentle AI (RDD)](https://github.com/Gentleman-Programming/gentle-ai)** | Adversarial Review Gate | Enforces Review-Driven Development (RDD) with multi-lens inspection before commits. | Graceful skip (`verify_rdd_review_gate` advisory check passes). |
-| ⚡ **Native Stack Linters** | AST & Type Safety | `ruff` (Python), `golangci-lint` (Go), `cargo clippy` (Rust), `phpstan` (PHP), `tsc` (TypeScript). | Uses whatever CLI is available in the local repository environment. |
-
----
-
-## 🧠 5. The Conversational CLI Paradigm
-
-CLC Kernel operates both in your terminal and inside your AI chat. It injects an **Agentic Playbook (`SKILL.md`)**, turning your LLM into an interactive governance orchestrator:
-
-- 🚀 **`clckernel start`**: Auto-detects your stack, proposes an AIUP lifecycle, and generates `.clckernel.yaml`.
-- 🛠️ **`clckernel create_guard`**: Generates a custom AST linter in your stack's native language (`tools/guards/`).
-- 🔄 **`clckernel add_phase` / `remove_guard`**: Interactively mutates the AIUP workflow without manual YAML editing.
-
----
-
-## 🌐 6. Polyglot Stack Adapters
-
-CLC Kernel includes dedicated adapters for popular technology stacks:
-
-| Ecosystem | Detection Signature | Test Runner | Enforced Safeguards |
-|---|---|---|---|
-| ⚛️ **Next.js** | `next` | Vitest / Jest | UI Reuse, Semantic Tokens, RSC Rules, Zod, A11y, Responsive, SEO, Performance |
-| ⚡ **FastAPI** | `fastapi` | Pytest | Pydantic V2, Alembic Idempotency, Clean Arch AST, DB Efficiency (N+1) |
-| 💎 **Rails** | `Gemfile` | RSpec | RuboCop AST, Brakeman Security, Migration Idempotency |
-| 🐹 **Golang** | `go.mod` | `go test` | `golangci-lint` AST, Domain/UseCase Clean Architecture |
-| 🦀 **Rust** | `Cargo.toml` | `cargo test` | `cargo clippy` AST, `cargo audit`, Strict Memory Safety |
-| 🐘 **Laravel** | `artisan` | Pest / PHPUnit | PHPStan AST, Eloquent N+1 Detection, Migrations |
-| 🎸 **Django** | `manage.py` | `pytest-django` | Django ORM Idempotency, Ruff AST, Scope Guard, DB Efficiency (N+1) |
-| 🚀 **Astro** | `astro.config` | Playwright | Tailwind v4 Tokens, Content Collection Schema, A11y, Responsive, SEO |
+1. **SDD (Spec-Driven Development):** Agent must write a local, gitignored specification (`sdds/{feature}/spec.md`) before editing production files.
+2. **HIT (Human-in-the-Loop):** The engineer reviews and approves test scenarios and contracts before execution begins.
+3. **TDD (Red-to-Green):** Agent must prove failure with a failing regression test (Red Phase) before writing implementation code (Green Phase).
+4. **AST (Deterministic Safeguards):** Native stack parsers (Python `ast`, Go `ast`, RuboCop, TypeScript AST) inspect diffs and physically block invalid commits.
+5. **SSOT (Single Source of Truth):** `AGENTS.md` is forged once and mirrored via filesystem symlinks to `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, and Copilot.
 
 ---
 
-## ⚡ 7. Step-by-Step Guide (Full Lifecycle)
+<a id="step-by-step-guide"></a>
+## ⚡ Step-by-Step Guide (Full Lifecycle)
 
 ```
 [1. Terminal]           [2. AI Chat]                 [3. TDD Loop]                 [4. Git Commit]
@@ -137,31 +72,88 @@ npx clckernel   ───►   clckernel start   ───►   "Feature X with
 
 ### 1️⃣ Step 1: Bootstrap the Repository (Terminal)
 ```bash
-npx clckernel
+npx clckernel start
 ```
-Auto-detects your framework, generates `AGENTS.md`, creates dynamic IDE symlinks, provisions pre-commit hooks (`.husky/` or `.githooks/`), and creates stack-native AST tools in `tools/`.
+Auto-detects your framework, generates `AGENTS.md`, creates dynamic IDE symlinks (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`), provisions pre-commit hooks, and creates native AST checks in `tools/`.
 
 ### 2️⃣ Step 2: Initialize in Your AI Chat (Conversational CLI)
 Open Cursor, Claude Code, Gemini CLI, Windsurf, or Copilot and type:
 > `clckernel start`
+
 The agent scans your codebase silently, proposes an AIUP governance plan tailored to your framework, and generates `.clckernel.yaml`.
 
 ### 3️⃣ Step 3: Develop with the AIUP Harness
-When requesting features or fixes, trigger the workflow:
-> *"Add user authentication endpoint. **Use the workflow / harness**."*
-The agent executes the full AIUP cycle: **SDD Spec -> HIT Approval -> TDD Red Phase -> Clean Implementation -> AST Audit**.
-
-### 4️⃣ Step 4: Deterministic Guard Verification (Commit)
+When requesting features or bugfixes, instruct your agent:
+> *"Add user authentication endpoint. **Follow the CLC Kernel harness**."*
+
+The agent autonomously executes the complete AIUP cycle:
+1. **Research & Root Cause Analysis:** Inspects codebase and dependencies.
+2. **Local SDD Spec:** Writes API contracts and test plans in `sdds/{change}/spec.md`.
+3. **HIT Review:** Requests your review and approval on proposed contracts.
+4. **TDD Red Phase:** Writes a failing regression test proving the requirement.
+5. **Clean Implementation (Green Phase):** Writes minimal code to pass tests while respecting layer isolation.
+6. **AST Audit Gate:** Runs `node tools/audit.js` and outputs the verification summary.
+
+### 4️⃣ Step 4: Deterministic Guard Verification (Git Commit)
 ```bash
 git add .
 git commit -m "feat(auth): add user authentication endpoint"
 ```
-Pre-commit hooks execute AST scanners (Clean Architecture, Secret Leaks, Scope Guard, Migration Idempotency). Non-compliant commits are blocked deterministically.
+Pre-commit hooks automatically execute AST scanners (Clean Architecture, Secret Leaks, Scope Guard, Migration Idempotency). Any non-compliant commit is **physically blocked** before touching Git history.
 
-### 5️⃣ Step 5: Verify Repository Health Anytime (Terminal)
+### 5️⃣ Step 5: Verify Repository Health Anytime (Doctor)
 ```bash
 npx clckernel doctor
 ```
-Runs the **CLC Kernel Doctor** to verify 100% compliance across `AGENTS.md`, `sdds/`, `tools/`, and Git hooks.
+Audits 100% compliance across `AGENTS.md`, `sdds/`, `tools/`, active test runners, and Git hooks.
+
+---
+
+<a id="universal-command-interface"></a>
+## 🎮 Universal Command Interface (All LLMs & Agents)
+
+CLC Kernel provides a deterministic command grammar supported natively by **Claude Code, Cursor, Codeium/Windsurf, Copilot, Gemini, and Antigravity**:
 
+| Command | Category | Mandatory Execution Protocol |
+|---|---|---|
+| `clckernel feature <name>` | Feature | Full AIUP cycle: Research -> Local Spec (`sdds/{name}/spec.md`) -> HIT review -> TDD Red Phase -> Green Implementation -> Audit. |
+| `clckernel fix <issue>` | Bug Fix | Root-cause analysis (no direct code edits) -> Failing regression test -> Surgical clean fix -> Audit gate. |
+| `clckernel test` | Verification | Runs repository test suite in the native stack runner and confirms clean pass. |
+| `clckernel audit` | Verification | Runs `node tools/audit.js` or `python tools/audit.py` and emits the Educational Summary. |
+| `clckernel doctor` | Diagnostics | Checks Git pre-commit hooks, IDE mirror symlinks, and AST engine integrity. |
+| `clckernel commit <message>` | Version Control | Pre-flight audit, verifies diff vs SDD scope, and commits with Conventional Commits (zero AI attribution). |
+| `clckernel guard create <name>` | Safeguards | Scaffolds a new AST guard script in the stack's native language in `tools/guards/`. |
+| `clckernel start` | Setup | Auto-detects stack, proposes AIUP lifecycle, and generates `.clckernel.yaml`. |
+
+---
+
+<a id="supported-stacks"></a>
+## 🌐 Supported Stacks & Archetypes
+
+| Ecosystem | Detection Signature | Test Runner | Native Safeguards |
+|---|---|---|---|
+| ⚛️ **Next.js** | `next` | Vitest / Jest | Clean Arch, UI Reuse, Semantic Tokens, RSC, A11y, Responsive, SEO |
+| ⚡ **FastAPI** | `fastapi` | Pytest | Pydantic V2, Alembic Idempotency, Clean Arch AST, DB Efficiency (N+1) |
+| 💎 **Rails** | `Gemfile` | RSpec | RuboCop AST, Brakeman Security, Migration Idempotency |
+| 🐹 **Golang** | `go.mod` | `go test` | `golangci-lint` AST, Domain/UseCase Layer Isolation |
+| 🦀 **Rust** | `Cargo.toml` | `cargo test` | `cargo clippy` AST, `cargo audit`, Strict Memory Safety |
+| 🐘 **Laravel** | `artisan` | Pest / PHPUnit | PHPStan AST, Eloquent N+1 Loop Detection, Migrations |
+| 🎸 **Django** | `manage.py` | `pytest-django` | Django ORM Idempotency, Ruff AST, Scope Guard, DB Efficiency (N+1) |
+| 🚀 **Astro** | `astro.config` | Playwright | Tailwind v4 Tokens, Content Schema, A11y, Responsive, SEO |
+| 🤖 **Agent-OS** | `skills/`, `brand/`, `templates/` | Contract Tests | Dual-Layer AGENTS.md, HITL Gates (`check_hitl`), Symlinks (`check_symlinks`), Domain Data (`check_domain_data`) |
+
+---
+
+<a id="ecosystem-companions"></a>
+## 🧩 Optional Ecosystem Companions
+
+CLC Kernel focuses strictly on governance and runs with **zero foreign dependencies**. It seamlessly integrates with companion tools:
+- 🧠 **[Engram (MCP)](https://github.com/Gentleman-Programming/gentle-ai):** Persistent architectural memory and ADR tracking across agent sessions.
+- 🕸️ **[Graphify](https://github.com/carlosleoncode/graphify):** Visual dependency graphs and codebase topology mapping.
+- 🛡️ **[Gentle AI (RDD)](https://github.com/Gentleman-Programming/gentle-ai):** Multi-lens adversarial code review gate.
+
+---
 
+<a id="license"></a>
+## 📄 License
+MIT © [CarlosLeonCode](https://github.com/carlosleoncode)

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "clckernel",
-  "version": "1.2.6",
+  "version": "1.2.9",
   "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",
+    "README.md",
+    "README.es.md"
+  ],
   "bin": {
     "clckernel": "bin/cli.js",
     "create-clckernel": "bin/cli.js",
@@ -39,6 +46,11 @@
   "scripts": {
     "test": "node --test test/*.test.js test/**/*.test.js",
     "test:unit": "node --test test/adapters/*.test.js",
-    "test:coverage": "NODE_V8_COVERAGE=coverage node --test test/*.test.js test/**/*.test.js"
+    "test:coverage": "NODE_V8_COVERAGE=coverage node --test test/*.test.js test/**/*.test.js",
+    "website:dev": "npm --prefix website run dev",
+    "website:build": "npm --prefix website run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
   }
 }