clckernel 1.2.13 → 1.2.18

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/README.es.md

@@ -20,11 +20,14 @@ Los agentes de programación con IA (Cursor, Claude Code, Windsurf, Copilot) cod
 ## 📋 Tabla de Contenidos
 - [🎯 Casos de Uso](#-casos-de-uso)
 - [🏛️ El Proceso Unificado de IA (AIUP)](#️-el-proceso-unificado-de-ia-aiup)
+- [🔍 Desarrollo Guiado por Revisión (RDD) y los 4 Lentes](#-desarrollo-guiado-por-revisión-rdd-y-los-4-lentes)
 - [⚡ Guía Paso a Paso (Ciclo Completo)](#-guía-paso-a-paso-ciclo-completo)
 - [🎮 Interfaz Universal de Comandos](#-interfaz-universal-de-comandos)
 - [🔄 Actualización de Proyectos Existentes](#-actualización-de-proyectos-existentes)
 - [🌐 Ecosistemas Soportados y Arquetipos](#-ecosistemas-soportados-y-arquetipos)
+- [🏛️ Arquitectura: Standalone vs. Simbiosis con Gentle AI](#-arquitectura-standalone-vs-simbiosis-con-gentle-ai)
 - [🧩 Herramientas Complementarias (Opcionales)](#-herramientas-complementarias-opcionales)
+- [📖 Glosario de Términos Clave](#-glosario-de-términos-clave)
 - [📄 Licencia](#-licencia)
 
 ---
@@ -62,6 +65,28 @@ Los agentes de programación con IA (Cursor, Claude Code, Windsurf, Copilot) cod
 
 ---
 
+<a id="rdd-y-lentes"></a>
+## 🔍 Desarrollo Guiado por Revisión (RDD) y los 4 Lentes
+
+CLC Kernel estructura todas sus compuertas de auditoría bajo los principios de **Review-Driven Development (RDD)**, organizando cada salvaguarda en torno a los **4 Lentes Canónicos de Revisión**:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       LOS 4 LENTES CANÓNICOS DE REVISIÓN                    │
+├─────────────────────┬───────────────────┬───────────────────┬───────────────┤
+│    🎯 CORRECTITUD   │    🛡️ SEGURIDAD   │  🏛️ ARQUITECTURA  │ ⚡ RENDIMIENTO│
+│ Bugs funcionales,   │ Fuga de secretos, │ Violación capas,  │ N+1 queries,  │
+│ scope drift, TDD,   │ bypass permisos,  │ límites de dominio│ tamaño bundle,│
+│ contratos API       │ eval peligroso    │ deps circulares   │ memory leaks  │
+└─────────────────────┴───────────────────┴───────────────────┴───────────────┘
+```
+
+Al ejecutar `clckernel audit` (o `node tools/audit.js`), CLC Kernel genera:
+1. **Informe Educativo para Humanos (`05-audit-report.md`):** Explica detalladamente qué pasó, falló o fue omitido agrupado por cada lente.
+2. **Recibo Inmutable de Auditoría (`audit-receipt.json`):** Un archivo JSON inmutable y legible por máquina vinculado al `commitHash` actual que certifica el resultado para compuertas automatizadas de revisión (como Gentle AI).
+
+---
+
 <a id="guia-paso-a-paso"></a>
 ## ⚡ Guía Paso a Paso (Ciclo Completo)
 
@@ -169,6 +194,49 @@ clckernel update
 
 ---
 
+<a id="arquitectura-simbiosis"></a>
+## 🏛️ Arquitectura: Standalone vs. Simbiosis con Gentle AI
+
+CLC Kernel está diseñado bajo una **filosofía de cero dependencias forzadas**: opera como un motor de gobernanza 100% autosuficiente y local, ofreciendo a su vez interoperabilidad nativa y fluida con el ecosistema de [Gentle AI](https://github.com/Gentleman-Programming/gentle-ai).
+
+<div align="center">
+  <img src="./docs/Architecture/clckernel-symbiosis.visual-check.2048x1320.dark.png" alt="CLC Kernel Standalone vs Simbiosis con Gentle AI (Diagrama Archify)" width="100%" />
+</div>
+
+> 💡 *Diagrama Interactivo: Generado con [Archify](https://github.com/tt-a1i/archify). Podés abrir [`docs/Architecture/clckernel-symbiosis.html`](./docs/Architecture/clckernel-symbiosis.html) para explorar la animación de flujo, cambiar entre modo claro/oscuro e inspeccionar detalles de cada nodo.*
+
+```mermaid
+flowchart TD
+  subgraph CORE["🤖 CLC KERNEL (Motor Central de Gobernanza)"]
+    SSOT["1. Ley SSOT<br/>(AGENTS.md y Symlinks para IDEs)"]
+    AIUP["2. Arnés AIUP<br/>(SDD + HITL + TDD Rojo-a-Verde)"]
+    AST["3. Linters AST &lt;5ms<br/>(Reglas de Capas, Secretos y Migraciones)"]
+    RECEIPT["4. Motor de Auditoría 4-Lentes<br/>(Genera audit-receipt.json)"]
+    SSOT --> AIUP --> AST --> RECEIPT
+  end
+
+  RECEIPT -->|audit-receipt.json| MODES{Modo de Ejecución}
+
+  subgraph MODE1["🟢 MODO 1: STANDALONE (100% Local y Desconectado)"]
+    M1_1["• Cero dependencias externas"]
+    M1_2["• Ejecución nativa AST en &lt; 5ms"]
+    M1_3["• Hook Git pre-commit bloquea físicamente commits inválidos"]
+    M1_4["• Reporte autosuficiente 05-audit-report.md"]
+  end
+
+  subgraph MODE2["🟣 MODO 2: + SIMBIOSIS CON GENTLE AI"]
+    M2_1["🧠 Engram (MCP): Contexto persistente y seguimiento de ADRs"]
+    M2_2["🛡️ Gentle AI (RDD): Revisión multi-agente adversarial"]
+    M2_3["🕸️ Graphify: Topología de código y análisis de impacto"]
+    M2_4["🔗 Sin bloqueo de proveedor: Consume audit-receipt.json sin fricción"]
+  end
+
+  MODES -->|Solo Local| MODE1
+  MODES -->|Con Herramientas Companion| MODE2
+```
+
+---
+
 <a id="herramientas-complementarias"></a>
 ## 🧩 Herramientas Complementarias (Opcionales)
 
@@ -179,6 +247,24 @@ CLC Kernel se enfoca estrictamente en gobernanza y opera con **cero dependencias
 
 ---
 
+<a id="glosario"></a>
+## 📖 Glosario de Términos Clave
+
+| Término | Definición |
+|---|---|
+| **SDD** *(Spec-Driven Development)* | Metodología orientada a especificaciones previas donde los contratos técnicos, esquemas, criterios de aceptación y escenarios de prueba se redactan en specs locales gitignoradas (`sdds/{cambio}/spec.md`) antes de modificar código fuente. |
+| **RDD** *(Review-Driven Development)* | Metodología de verificación adversarial y estructurada donde los cambios se auditan a través de cuatro lentes ortogonales (Correctitud, Seguridad, Arquitectura y Rendimiento) para garantizar compuertas sistemáticas de calidad antes del merge o commit. |
+| **AIUP** *(AI Unified Process)* | El ciclo de vida gobernado de punta a punta implementado por CLC Kernel: Investigación $\rightarrow$ SDD local $\rightarrow$ Aprobación Human-in-the-Loop (HITL) $\rightarrow$ TDD Rojo a Verde $\rightarrow$ Compuerta de Auditoría AST $\rightarrow$ Conventional Commit. |
+| **HIT / HITL** *(Human-in-the-Loop)* | Compuerta obligatoria de aprobación donde un ingeniero humano valida contratos, decisiones arquitectónicas y pruebas propuestas antes de que un agente autónomo edite código de producción. |
+| **TDD** *(Test-Driven Development)* | Práctica de ingeniería de reproducir bugs o especificar nuevas funcionalidades mediante un test automatizado que falle (Fase Roja) antes de escribir el código mínimo de producción para que pase (Fase Verde). |
+| **Guard AST** *(Salvaguarda de Árbol de Sintaxis Abstracta)* | Script liviano de análisis estático sin dependencias foráneas escrito en el lenguaje nativo del stack (Python `ast`, TypeScript Compiler API, Go `go/parser`, RuboCop, etc.) que se ejecuta en menos de 5ms para bloquear físicamente violaciones antes del commit. |
+| **SSOT** *(Single Source of Truth / Única Fuente de Verdad)* | Principio de gobernanza centralizada donde `AGENTS.md` funciona como la ley única, proyectándose automáticamente a todos los entornos de agentes (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, Copilot) mediante symlinks del sistema de archivos. |
+| **Recibo de Auditoría** *(Audit Receipt)* | Artefacto JSON inmutable y legible por máquina (`audit-receipt.json`) producido por el motor de auditoría con la marca de tiempo, hash del commit, veredictos por cada lente y metadatos de compatibilidad RDD para Gentle AI. |
+| **ADR** *(Architectural Decision Record)* | Documento estandarizado bajo `docs/Journal/` que captura decisiones arquitectónicas clave, contexto histórico, alternativas evaluadas y consecuencias. |
+| **Agent-OS** | Arquetipo de sistema operativo para flujos de agentes y dominios no técnicos (por ejemplo: Marketing OS, Content Ops, Research OS) gobernado por arquitectura de dos capas, validación estricta de esquemas y compuertas HITL. |
+
+---
+
 <a id="licencia"></a>
 ## 📄 Licencia
 MIT © [CarlosLeonCode](https://github.com/carlosleoncode)

package/README.md

@@ -20,11 +20,14 @@ AI coding agents (Cursor, Claude Code, Windsurf, Copilot) code fast, but without
 ## 📋 Table of Contents
 - [🎯 Use Cases](#-use-cases)
 - [🏛️ The AI Unified Process (AIUP)](#️-the-ai-unified-process-aiup)
+- [🔍 Review-Driven Development (RDD) & the 4 Canonical Lenses](#-review-driven-development-rdd--the-4-canonical-lenses)
 - [⚡ Step-by-Step Guide (Full Lifecycle)](#-step-by-step-guide-full-lifecycle)
 - [🎮 Universal Command Interface](#-universal-command-interface)
 - [🔄 Updating an Existing Project](#-updating-an-existing-project)
 - [🌐 Supported Stacks & Archetypes](#-supported-stacks--archetypes)
+- [🏛️ Architecture: Standalone vs. Gentle AI Symbiosis](#-architecture-standalone-vs-gentle-ai-symbiosis)
 - [🧩 Optional Ecosystem Companions](#-optional-ecosystem-companions)
+- [📖 Glossary of Key Terms](#-glossary-of-key-terms)
 - [📄 License](#-license)
 
 ---
@@ -62,6 +65,28 @@ AI coding agents (Cursor, Claude Code, Windsurf, Copilot) code fast, but without
 
 ---
 
+<a id="rdd-and-lenses"></a>
+## 🔍 Review-Driven Development (RDD) & the 4 Canonical Lenses
+
+CLC Kernel structures all verification and audit gates around **Review-Driven Development (RDD)**, categorizing every safeguard across the **4 Canonical Review Lenses**:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       THE 4 CANONICAL REVIEW LENSES                         │
+├─────────────────────┬───────────────────┬───────────────────┬───────────────┤
+│    🎯 CORRECTNESS   │    🛡️ SECURITY    │  🏛️ ARCHITECTURE  │ ⚡ PERFORMANCE│
+│ Functional bugs,    │ Secret leaks,     │ Layer violations, │ N+1 queries,  │
+│ scope drift, TDD,   │ permission bypass,│ domain boundaries,│ bundle size,  │
+│ API contracts       │ dangerous eval    │ circular deps     │ memory leaks  │
+└─────────────────────┴───────────────────┴───────────────────┴───────────────┘
+```
+
+When you run `clckernel audit` (or `node tools/audit.js`), CLC Kernel generates:
+1. **Human-Readable Educational Report (`05-audit-report.md`):** Explains exactly what passed, failed, or was skipped grouped by lens.
+2. **Machine-Readable Audit Receipt (`audit-receipt.json`):** An immutable JSON receipt bound to the active `commitHash` certifying the verdict for automated review gates (such as Gentle AI).
+
+---
+
 <a id="step-by-step-guide"></a>
 ## ⚡ Step-by-Step Guide (Full Lifecycle)
 
@@ -169,6 +194,49 @@ clckernel update
 
 ---
 
+<a id="architecture-symbiosis"></a>
+## 🏛️ Architecture: Standalone vs. Gentle AI Symbiosis
+
+CLC Kernel is architected with a **zero-lock-in philosophy**: it functions as a 100% self-sufficient local governance engine, while offering seamless, native interoperability with the [Gentle AI](https://github.com/Gentleman-Programming/gentle-ai) ecosystem.
+
+<div align="center">
+  <img src="./docs/Architecture/clckernel-symbiosis.visual-check.2048x1320.dark.png" alt="CLC Kernel Standalone vs Gentle AI Symbiosis (Archify Diagram)" width="100%" />
+</div>
+
+> 💡 *Interactive Diagram: Built with [Archify](https://github.com/tt-a1i/archify). Open [`docs/Architecture/clckernel-symbiosis.html`](./docs/Architecture/clckernel-symbiosis.html) for full trace animation, theme switching, and deep-link node inspection.*
+
+```mermaid
+flowchart TD
+  subgraph CORE["🤖 CLC KERNEL (Core Governance Engine)"]
+    SSOT["1. SSOT Law<br/>(AGENTS.md & IDE Mirrors)"]
+    AIUP["2. AIUP Harness<br/>(SDD + HITL + TDD Red-to-Green)"]
+    AST["3. AST Guards &lt;5ms<br/>(Layer, Secret & Migration Rules)"]
+    RECEIPT["4. 4-Lens Audit Engine<br/>(Emits audit-receipt.json)"]
+    SSOT --> AIUP --> AST --> RECEIPT
+  end
+
+  RECEIPT -->|audit-receipt.json| MODES{Deployment Mode}
+
+  subgraph MODE1["🟢 MODE 1: STANDALONE (100% Local & Offline)"]
+    M1_1["• Zero foreign dependencies"]
+    M1_2["• Native stack AST execution in &lt; 5ms"]
+    M1_3["• Git pre-commit hook physically blocks invalid commits"]
+    M1_4["• Self-contained 05-audit-report.md"]
+  end
+
+  subgraph MODE2["🟣 MODE 2: + GENTLE AI SYMBIOSIS"]
+    M2_1["🧠 Engram (MCP): Persistent context & ADR tracking"]
+    M2_2["🛡️ Gentle AI (RDD): Multi-agent adversarial review"]
+    M2_3["🕸️ Graphify: Codebase topology & blast radius analysis"]
+    M2_4["🔗 Zero-Lock-In: Consumes audit-receipt.json seamlessly"]
+  end
+
+  MODES -->|Local Only| MODE1
+  MODES -->|With Companions| MODE2
+```
+
+---
+
 <a id="ecosystem-companions"></a>
 ## 🧩 Optional Ecosystem Companions
 
@@ -179,6 +247,24 @@ CLC Kernel focuses strictly on governance and runs with **zero foreign dependenc
 
 ---
 
+<a id="glossary"></a>
+## 📖 Glossary of Key Terms
+
+| Term | Definition |
+|---|---|
+| **SDD** *(Spec-Driven Development)* | A specification-first methodology where detailed technical contracts, schemas, acceptance criteria, and test scenarios are authored in local, gitignored specs (`sdds/{change}/spec.md`) before modifying source code. |
+| **RDD** *(Review-Driven Development)* | An adversarial and structured code verification methodology where changes are audited across four orthogonal lenses (Correctness, Security, Architecture, Performance) to ensure systematic quality gates before merge or commit. |
+| **AIUP** *(AI Unified Process)* | The end-to-end governed lifecycle implemented by CLC Kernel: Research $\rightarrow$ Local SDD $\rightarrow$ Human-in-the-Loop (HITL) approval $\rightarrow$ TDD Red-to-Green $\rightarrow$ AST Guard Audit Gate $\rightarrow$ Conventional Commit. |
+| **HIT / HITL** *(Human-in-the-Loop)* | A mandatory approval gate where a human engineer validates contracts, architecture decisions, and proposed tests before an autonomous agent executes production code edits. |
+| **TDD** *(Test-Driven Development)* | The engineering practice of writing a failing automated regression test (Red Phase) to reproduce an issue or specify a new feature before writing the minimal production code to make it pass (Green Phase). |
+| **AST Guard** *(Abstract Syntax Tree Safeguard)* | A lightweight, zero-dependency static analysis script in the stack's native language (Python `ast`, TypeScript Compiler API, Go `go/parser`, RuboCop, etc.) executing in under 5ms to physically block architectural violations before git commits. |
+| **SSOT** *(Single Source of Truth)* | The centralized governance principle where `AGENTS.md` acts as the single source of truth, mirrored automatically to all AI IDE config files (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, Copilot) via filesystem symlinks. |
+| **Audit Receipt** | An immutable, machine-readable JSON artifact (`audit-receipt.json`) produced by the audit engine containing the timestamp, commit hash, per-lens verdicts, and Gentle AI RDD compatibility metadata. |
+| **ADR** *(Architectural Decision Record)* | A standardized document in `docs/Journal/` capturing significant architectural decisions, context, evaluated alternatives, and consequences. |
+| **Agent-OS** | An operating system archetype for non-tech domain workflows (e.g. Marketing OS, Content Ops, Research OS) governed by dual-layer architecture, strict schema validation, and HITL checkpoints. |
+
+---
+
 <a id="license"></a>
 ## 📄 License
 MIT © [CarlosLeonCode](https://github.com/carlosleoncode)

package/package.json

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

package/src/adapters/agent-os.js

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