clckernel 1.2.6 → 1.2.8

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,28 @@
 [![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
-
-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)**.
+## 🎯 Casos de Uso
 
-| 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. |
+| 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":
+## 🏛️ El Proceso Unificado de IA (AIUP)
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
@@ -43,124 +40,60 @@ 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.*
+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.
 
 ---
 
-## 💡 3. Por Qué Existe CLC Kernel
+## 🌐 Ecosistemas Soportados y Arquetipos
 
-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á |
+| Ecosistema | Firma de Detección | Test Runner | Salvaguardas Nativas |
 |---|---|---|---|
-| 🧠 **[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.
-
----
-
-## 🌐 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) |
+| ⚛️ **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`, 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 |
+| 🐹 **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, Content Collection Schema, A11y, Responsive, SEO |
+| 🚀 **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`) |
 
 ---
 
-## ⚡ 7. Guía Paso a Paso (Ciclo de Vida Completo)
+## 🚀 Inicio Rápido
 
+### 1. Inicializar en Terminal
+```bash
+npx clckernel start
 ```
-[1. Terminal]           [2. Chat del LLM]            [3. Bucle TDD]                [4. Git Commit]
-npx clckernel   ───►   clckernel start   ───►   "Feature X con harness"   ───►   Hooks Pre-commit
-(Bootstrap)            (Setup Interactivo)          (SDD -> HIT -> Tests)         (Guardián AST & Secretos)
-```
+Detecta el framework, genera `AGENTS.md`, crea symlinks para todos los IDEs, provisiona hooks pre-commit e instala verificadores AST en `tools/`.
 
-### 1️⃣ Paso 1: Inicializar el Repositorio (Terminal)
+### 2. Verificar Estado de Salud
 ```bash
-npx clckernel
+npx clckernel doctor
 ```
-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/`.
+Audita hooks de Git, test runners activos y la integridad del motor AST.
 
-### 2️⃣ Paso 2: Abrir tu IDE con IA e Inicializar (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. Desarrollar con Gobernanza
+En el chat del IDE (Cursor, Claude Code, Gemini CLI, Windsurf):
+> *"Implementa el endpoint de autenticación. **Usa el harness de CLC Kernel**."*
 
-### 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 ejecutará el ciclo AIUP completo: **Especificación SDD -> Aprobación HIT -> Test Rojo -> Implementación Verde -> Auditoría AST**.
 
-### 4️⃣ Paso 4: Verificación Determinística de Guards (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.
+---
 
-### 5️⃣ Paso 5: Auditar la Salud del Repositorio en Cualquier Momento (Terminal)
-```bash
-npx clckernel doctor
-```
-Ejecuta el **CLC Kernel Doctor** para verificar el 100% de cumplimiento en `AGENTS.md`, `sdds/`, `tools/` y hooks de Git.
+## 🧩 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.
+
+---
 
+## 📄 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,28 @@
 [![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
+## 🎯 Use Cases
 
-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. |
+| 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:
+## 🏛️ The AI Unified Process (AIUP)
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
@@ -43,125 +40,60 @@ 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.
+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.
 
 ---
 
-## 🌐 6. Polyglot Stack Adapters
+## 🌐 Supported Stacks & Archetypes
 
-CLC Kernel includes dedicated adapters for popular technology stacks:
-
-| Ecosystem | Detection Signature | Test Runner | Enforced Safeguards |
+| Ecosystem | Detection Signature | Test Runner | Native Safeguards |
 |---|---|---|---|
-| ⚛️ **Next.js** | `next` | Vitest / Jest | UI Reuse, Semantic Tokens, RSC Rules, Zod, A11y, Responsive, SEO, Performance |
+| ⚛️ **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 Clean Architecture |
+| 🐹 **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 Detection, Migrations |
+| 🐘 **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 Collection Schema, A11y, Responsive, SEO |
+| 🚀 **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`) |
 
 ---
 
-## ⚡ 7. Step-by-Step Guide (Full Lifecycle)
+## 🚀 Quickstart
 
+### 1. Initialize in Terminal
+```bash
+npx clckernel start
 ```
-[1. Terminal]           [2. AI Chat]                 [3. TDD Loop]                 [4. Git Commit]
-npx clckernel   ───►   clckernel start   ───►   "Feature X with harness"   ───►   Pre-commit Hooks
-(Bootstrap)            (Interactive Setup)          (SDD -> HIT -> Tests)         (AST & Secret Guard)
-```
+Auto-detects your framework, generates `AGENTS.md`, creates IDE rule symlinks, provisions pre-commit hooks, and creates native AST checks in `tools/`.
 
-### 1️⃣ Step 1: Bootstrap the Repository (Terminal)
+### 2. Verify Health
 ```bash
-npx clckernel
+npx clckernel doctor
 ```
-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/`.
+Audits Git hooks, active test runners, and AST engine integrity.
 
-### 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. Develop with Agentic Governance
+In your IDE chat (Cursor, Claude Code, Gemini CLI, Windsurf):
+> *"Implement authentication endpoint. **Follow the CLC Kernel harness**."*
 
-### 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**.
+The agent executes the full AIUP loop: **SDD Spec -> HIT Review -> Failing Test (Red) -> Implementation (Green) -> AST Audit**.
 
-### 4️⃣ Step 4: Deterministic Guard Verification (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.
+---
 
-### 5️⃣ Step 5: Verify Repository Health Anytime (Terminal)
-```bash
-npx clckernel doctor
-```
-Runs the **CLC Kernel Doctor** to verify 100% compliance across `AGENTS.md`, `sdds/`, `tools/`, and Git hooks.
+## 🧩 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.
+
+---
 
+## 📄 License
+MIT © [CarlosLeonCode](https://github.com/carlosleoncode)

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "clckernel",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "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"
   }
 }