clckernel 1.2.6

package/AGENTS.md

@@ -0,0 +1,124 @@
+# 🔨 CLC Kernel (Node.js / Polyglot Core) — AGENTS
+
+This document is the **authoritative law** for AI agents working in this repository.
+Forged by **CLC Kernel: The AI Agent Governance Engine**.
+
+---
+
+## 🎯 Project Identity & Category
+**CLC Kernel (`clckernel`)** is the Universal Polyglot AI Agent Governance Engine & AIUP Orchestrator.
+It creates and owns a new category in software engineering: **Deterministic AI Agent Governance**.
+
+Unlike prompt-based rules (`.cursorrules`) or backend agent runtimes (LangGraph), CLC Kernel provides an **in-repo developer harness** that deterministically forces AI coding agents to follow strict engineering lifecycles (SDD, TDD, Clean Architecture AST Linters) across multiple tech stacks (Next.js, FastAPI, Rails, Go, Rust, Laravel, Django, Astro).
+
+---
+
+> 🚨 **RULE #0: MANDATORY EXECUTION OVERRIDE RULE (UNBYPASSABLE)**
+> Even when the user issues a direct or urgent fix request ("fix this bug", "fix this error", "quick fix"):
+> YOU ARE STRICTLY FORBIDDEN from modifying source code directly without completing the full quality harness:
+> 1. **Research & Root Cause Analysis:** Investigate tracebacks and inspect affected files before editing.
+> 2. **TDD Verification (Red Phase):** Write a failing regression test first (`npm test`).
+> 3. **Clean Architecture Implementation (Green Phase):** Make the test pass maintaining layer isolation.
+> 4. **Mandatory Educational Audit Gate:** Execute `npm test` and verify zero lint/test regressions.
+> NEVER declare success or skip verification commands for quick fixes.
+
+---
+
+## 1. The Engineering Loop (Every Task)
+1. **Research** — Inspect codebase / docs / existing AST linters before writing code.
+2. **Plan** — Write an SDD under `sdds/{change-name}/` when introducing features or architectural refactors.
+3. **Test (TDD)** — Write failing tests first in `test/`.
+4. **Implement** — Write modular, zero-external-dependency code in `src/` or `tools/`.
+5. **Verify & Audit** — Run `npm test` (all 236+ test cases across catalog, adapters, generator, and detector).
+6. **DoD (Definition of Done)** — Clean code, zero regressions, full test coverage, docs updated in English and Spanish.
+7. **Commit** — Pre-commit hook runs automated guards. Use Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`). Never add AI co-authorship.
+
+---
+
+## 2. Core Repository Architecture & Layout
+
+```
+clckernel/
+├── bin/
+│   └── cli.js                  # Executable CLI entrypoint (clckernel, clc-kernel, clc-forge)
+├── src/
+│   ├── index.js                # CLI controller orchestration
+│   ├── catalog.js              # Central 26-guard registry (Single Source of Truth)
+│   ├── config.js               # .clckernel.yml loader & validator (ConfigError)
+│   ├── detector.js             # Stack auto-detection heuristics
+│   ├── doctor.js               # Repository health check engine (CLC KERNEL DOCTOR)
+│   ├── generator.js            # Universal harness, hook, and symlink provisioner
+│   ├── ui.js                   # Terminal UI, ASCII banner & ANSI renderer
+│   ├── yaml.js                 # Zero-dependency YAML parser & glob-to-regex engine
+│   ├── adapters/               # Polyglot stack adapters (Next.js, FastAPI, Rails, Go, Rust, Laravel, Django, Astro)
+│   └── technologies/           # Technology-specific detectors (Celery, Redis, Postgres, Docker)
+├── tools/                      # Deterministic AST linters & safeguard scripts (Node.js & Python stdlib)
+│   ├── audit.js / audit.py     # Multi-guard orchestrator gates
+│   ├── scan_secrets.js / .py   # Secret leak scanners
+│   ├── check_architecture.*    # Clean Architecture layer isolation checkers
+│   ├── check_custom.js / .py   # User-defined regex rules from .clckernel.yml
+│   ├── check_a11y.js           # ARIA & accessibility linter
+│   ├── check_ui_reuse.js       # UI primitive reuse enforcer
+│   ├── check_performance.js    # Next/Image & tree-shaking linter
+│   ├── check_responsive.js     # Mobile-first & touch target linter
+│   ├── check_seo.js            # OpenGraph, SEO & Core Web Vitals linter
+│   ├── check_storybook.js      # Storybook coverage guard
+│   ├── check_api_contracts.js  # Zod schema validation guard
+│   ├── check_migrations.py     # Alembic / Django migration idempotency guard
+│   ├── check_db_efficiency.py  # ORM N+1 & query efficiency guard
+│   ├── check_scope.py          # Git diff vs SDD authorized scope guard
+│   ├── verify_tdd.py           # Red-to-Green transition proof checker
+│   ├── celery_guard.py         # Celery broker & result backend safety guard
+│   ├── redis_guard.py          # Redis decode_responses & timeout guard
+│   ├── postgres_guard.py       # PostgreSQL raw query & injection guard
+│   └── docker_guard.py         # Docker non-root USER & healthcheck guard
+├── test/                       # Comprehensive node:test runner suites
+├── README.md                   # Primary documentation (English)
+├── README.es.md                # Primary documentation (Spanish)
+└── package.json                # Package manifest (@clckernel)
+```
+
+---
+
+## 3. Active Safeguard Catalog & Deterministic Rules
+
+All AI agents operating in repositories provisioned by CLC Kernel are deterministically governed by the following safeguard layers:
+
+### 📱 Frontend & UX Quality Safeguards
+- **`check_responsive.js`**: Enforces mobile-first responsive design, warns against fixed-width pixel overflows (`width: >400px` without media queries), and requires minimum touch targets (44x44px or 48x48px) for buttons and interactive controls.
+- **`check_seo.js`**: Validates essential SEO title/description tags, OpenGraph (`og:title`, `og:image`), GEO tags (`geo.position`, `ICBM`), heading hierarchy (`<h1>` uniqueness), and LCP image `priority` / `fetchpriority="high"`.
+- **`check_a11y.js`**: Audits ARIA roles, missing `alt` attributes on images, and keyboard navigable interactive controls.
+- **`check_ui_reuse.js`**: Prevents duplicate UI classes and arbitrary styling by enforcing the reuse of design system primitives in `components/ui/`.
+- **`check_performance.js`**: Enforces framework-native image optimization (`next/image`, `astro:assets`) and prevents barrel-file imports that break tree-shaking.
+- **`check_api_contracts.js`**: Enforces runtime schema validation (Zod) on all external HTTP requests and API boundaries.
+- **`check_storybook.js`**: Audits Storybook `.stories.tsx` coverage for all new UI primitives.
+
+### 🏛️ Backend, Architecture & Data Safeguards
+- **`check_architecture.js / .py`**: Validates Clean Architecture layer boundaries (Domain -> Use Case -> Interface -> Infrastructure) and prevents presentation/route handlers from calling DB queries directly.
+- **`check_db_efficiency.py`**: Detects N+1 query patterns in loops and enforces eager loading (`select_related`, `prefetch_related` in Django; `joinedload` in SQLAlchemy).
+- **`check_migrations.py`**: Ensures database migrations (Alembic / Django) are idempotent, reversible, and do not drop tables/columns destructively without down-revisions.
+- **`scan_secrets.js / .py`**: Scans diffs for private keys, AWS/Stripe credentials, JWT secrets, and hardcoded connection strings.
+- **`check_scope.py`**: Compares modified files against the authorized scope defined in the local SDD specification.
+- **`verify_tdd.py`**: Validates the transition proof from a failing regression test (Red Phase) to a passing implementation (Green Phase).
+
+### 🐳 Infrastructure & Technology Guards
+- **`docker_guard.py`**: Checks Dockerfiles for non-root `USER` directives, prevents `ENV` secret exposures, and requires `HEALTHCHECK` definitions.
+- **`celery_guard.py`**: Enforces broker URL isolation via environment variables, `@shared_task(ignore_result=True)` defaults, and secure backend configs.
+- **`redis_guard.py`**: Enforces `decode_responses=True`, mandatory `socket_connect_timeout`, and prevents hardcoded Redis host strings.
+- **`postgres_guard.py`**: Blocks raw SQL string formatting / Python f-strings in queries to prevent SQL injection vulnerabilities.
+
+---
+
+## 4. Recommended Ecosystem Companions
+CLC Kernel is strictly focused on **Governance, Process & Quality Guards**. It relies modularly on companion tools with graceful degradation:
+- 🧠 **Engram (MCP):** Long-term memory, session state, and architectural decision records (ADRs).
+- 🕸️ **Graphify:** Repository knowledge graphs and visual topology mapping.
+- 🛡️ **Gentle AI (RDD):** Review-Driven Development with adversarial dual-lens review gates.
+
+---
+
+## 5. Coding & Design Principles
+- **CONCEPTS > CODE:** Never add boilerplate without understanding architectural layer boundaries.
+- **Zero-Dependency Core:** The CLI engine and tool scripts must use native Node.js / Python built-ins wherever possible (zero runtime npm dependencies for the parser and linters).
+- **Polyglot Fidelity:** Native guards must be written in the ecosystem's native idioms (Go AST for Go, Python AST for Python, JS/TS AST for Node).
+- **Graceful Fallbacks:** If optional companion tools or optional linters are missing from the host machine, guards must degrade gracefully with advisory warnings rather than hard crashes.

package/README.es.md

@@ -0,0 +1,166 @@
+<div align="center">
+  <img width="350" height="350" alt="clckernel_logo" src="https://github.com/user-attachments/assets/2898e9c1-ec7a-4c60-a6dd-e62c05a0d446" />
+</div>
+
+# 🤖 CLC Kernel (`clckernel`)
+
+[![npm version](https://img.shields.io/npm/v/clckernel.svg)](https://www.npmjs.com/package/clckernel)
+[![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).
+
+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.
+
+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).
+
+---
+
+## 🎯 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)**.
+
+| 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. |
+
+---
+
+## 🏛️ 2. Pilares Conceptuales del Ecosistema
+
+CLC Kernel se apoya en cinco fundamentos de ingeniería diseñados para erradicar los vicios del "Vibe Coding":
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       AI UNIFIED PROCESS (AIUP)                             │
+├─────────────┬─────────────┬─────────────┬──────────────────┬────────────────┤
+│   1. SDD    │   2. HIT    │   3. TDD    │     4. AST       │   5. MIRROR    │
+│ Spec-Driven │ Human-in-the│ Transición  │ Linters de Capas │ Single Source  │
+│ Development │    Loop     │ Rojo-a-Verde│  Determinísticos │ of Truth Sync  │
+└─────────────┴─────────────┴─────────────┴──────────────────┴────────────────┘
+```
+
+### 📝 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.
+
+---
+
+## 🌐 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)
+
+```
+[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)
+```
+
+### 1️⃣ Paso 1: Inicializar el Repositorio (Terminal)
+```bash
+npx clckernel
+```
+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/`.
+
+### 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️⃣ 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**.
+
+### 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.
+

package/README.md

@@ -0,0 +1,167 @@
+<div align="center">
+  <img width="350" height="350" alt="clckernel_logo" src="https://github.com/user-attachments/assets/ed631ce1-c996-4347-b818-97b8ab25e0ec" />
+</div>
+
+# 🤖 CLC Kernel (`clckernel`)
+
+[![npm version](https://img.shields.io/npm/v/clckernel.svg)](https://www.npmjs.com/package/clckernel)
+[![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).
+
+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.
+
+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).
+
+---
+
+## 🎯 1. Positioning: A New Category — AI Agent Governance
+
+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. |
+
+---
+
+## 🏛️ 2. Core Conceptual Pillars
+
+CLC Kernel is built upon five foundational engineering principles designed to eliminate "vibe coding" hazards:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       AI UNIFIED PROCESS (AIUP)                             │
+├─────────────┬─────────────┬─────────────┬──────────────────┬────────────────┤
+│   1. SDD    │   2. HIT    │   3. TDD    │     4. AST       │   5. MIRROR    │
+│ Spec-Driven │ Human-in-the│ Red-to-Green│ Deterministic    │ Single Source  │
+│ Development │    Loop     │ Transitions │ Layer Linters    │ of Truth Sync  │
+└─────────────┴─────────────┴─────────────┴──────────────────┴────────────────┘
+```
+
+### 📝 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 |
+
+---
+
+## ⚡ 7. Step-by-Step Guide (Full Lifecycle)
+
+```
+[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)
+```
+
+### 1️⃣ Step 1: Bootstrap the Repository (Terminal)
+```bash
+npx clckernel
+```
+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/`.
+
+### 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)
+```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.
+
+

package/bin/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * CLC Kernel — Executable Binary Entry Point
+ * Invokes the main controller module for CLC Kernel.
+ */
+
+const { runCli } = require('../src/index');
+
+runCli().catch((err) => {
+  console.error('\n❌ Error ejecutando clckernel:', err);
+  process.exit(1);
+});

package/docs/Journal/001-adr-clckernel-governance.md

@@ -0,0 +1,18 @@
+# ADR 001: Deterministic AI Agent Governance Engine
+
+## Status
+Accepted
+
+## Context
+AI coding agents generate code rapidly but introduce technical debt, layer violations, and false-positive test transitions when operating without deterministic guardrails.
+
+## Decision
+Establish **CLC Kernel** (`clckernel`) as a polyglot AI Agent Governance harness implementing the AI Unified Process (AIUP):
+1. **Spec-Driven Development (SDD)** with Human-in-the-Loop gates.
+2. **Test-Driven Development (TDD)** requiring verified failing tests prior to implementation.
+3. **Deterministic AST Linters** tailored per tech stack (Go, Python, Rust, Ruby, JS/TS, PHP).
+4. **Universal IDE Symlinking** from `AGENTS.md` to all AI IDEs (Cursor, Claude, Gemini, Copilot, Antigravity).
+
+## Consequences
+- Guarantees architectural integrity and zero secret leaks.
+- Seamlessly integrates with Engram (memory) and Graphify (knowledge graph).

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "clckernel",
+  "version": "1.2.6",
+  "description": "CLC Kernel — The Universal Polyglot AI Agent Governance Engine (Next.js, FastAPI, Django, Astro, Rails, Go, Rust, Laravel).",
+  "main": "./bin/cli.js",
+  "bin": {
+    "clckernel": "bin/cli.js",
+    "create-clckernel": "bin/cli.js",
+    "clc-kernel": "bin/cli.js",
+    "clc-forge": "bin/cli.js",
+    "create-clc-forge": "bin/cli.js"
+  },
+  "keywords": [
+    "clckernel",
+    "clc-kernel",
+    "clc-forge",
+    "clc_forge",
+    "carlosleoncode",
+    "polyglot",
+    "agent-governance",
+    "nextjs",
+    "fastapi",
+    "django",
+    "astro",
+    "rails",
+    "golang",
+    "rust",
+    "laravel",
+    "vitest",
+    "pytest",
+    "husky",
+    "safeguards"
+  ],
+  "author": "Carlos Leon Code",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "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"
+  }
+}

package/src/adapters/astro.js

@@ -0,0 +1,67 @@
+/**
+ * CLC Kernel — Astro Stack Adapter
+ * Supports Astro components, Tailwind CSS v4, Vitest, A11y, and Storybook/MDX stories.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const BaseAdapter = require('./base');
+
+class AstroAdapter extends BaseAdapter {
+  constructor() {
+    super('Astro Framework', 'frontend', 'Vitest / Playwright');
+  }
+
+  detect(targetDir) {
+    const hasAstroConfig = fs.existsSync(path.join(targetDir, 'astro.config.mjs')) || fs.existsSync(path.join(targetDir, 'astro.config.js'));
+    const hasPkg = fs.existsSync(path.join(targetDir, 'package.json'));
+    if (!hasPkg) return false;
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(targetDir, 'package.json'), 'utf-8'));
+      const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      return hasAstroConfig || Boolean(deps['astro']);
+    } catch (e) {
+      return hasAstroConfig;
+    }
+  }
+
+  getSafeguards() {
+    return [
+      'Astro Component & UI Primitive Reuse First Guard',
+      'Tailwind v4 Semantic Design Token Guard',
+      'Accessibility & ARIA Guard (A11y & alt tags)',
+      'Responsive Design & Mobile-First Adaptability Guard (breakpoint & touch target audit)',
+      'SEO, GEO & Web Performance Guard (metadata, OpenGraph, Core Web Vitals)',
+      'Secret & API Key Leak Scanner',
+      'Content Collection Schema Validation Guard',
+      'Vitest / Playwright Red-to-Green TDD Validator',
+      'Educational Audit Gate (05-audit-report.md)',
+      'Memory Guard (Engram / Graphify ADR Sync)'
+    ];
+  }
+
+  /**
+   * Returns the tool manifest for Astro projects.
+   * Includes JS guard scripts and external CLI tools (astro check, vitest).
+   * @returns {Array<{name: string, language: string, path: string, command: string, description: string, extCLI?: string}>}
+   */
+  getTools() {
+    const baseTools = [
+      { name: 'scan_secrets',     language: 'js',       path: 'scan_secrets.js',     command: 'node tools/scan_secrets.js',     description: 'Scans for leaked secrets and API keys' },
+      { name: 'check_a11y',       language: 'js',       path: 'check_a11y.js',       command: 'node tools/check_a11y.js',       description: 'Validates ARIA and accessibility rules' },
+      { name: 'check_responsive', language: 'js',       path: 'check_responsive.js', command: 'node tools/check_responsive.js', description: 'Audits mobile-first responsiveness and fixed-width overflows' },
+      { name: 'check_seo',        language: 'js',       path: 'check_seo.js',        command: 'node tools/check_seo.js',        description: 'Validates SEO metadata, OpenGraph, GEO tags, and LCP priority' },
+      { name: 'check_custom',     language: 'js',       path: 'check_custom.js',     command: 'node tools/check_custom.js',     description: 'Runs user-defined custom rules from .clc-forge.yml' },
+      { name: 'astro_check',      language: 'external', path: '', command: 'npx astro check', description: 'Astro type checking', extCLI: 'astro' },
+      { name: 'vitest',           language: 'external', path: '', command: 'npx vitest run',  description: 'Test runner', extCLI: 'vitest' },
+    ];
+    return this._mergeTechTools(baseTools);
+  }
+
+  provision(targetDir, config) {
+    super.provision(targetDir, config);
+    // Pre-commit hook generation moved to generator.js via getTools() manifest
+  }
+}
+
+module.exports = AstroAdapter;