clckernel 1.2.17 → 1.2.19

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,6 +1,6 @@
 {
   "name": "clckernel",
-  "version": "1.2.17",
+  "version": "1.2.19",
   "description": "CLC Kernel — The Universal Polyglot AI Agent Governance Engine (Next.js, FastAPI, Django, Astro, Rails, Go, Rust, Laravel).",
   "main": "./bin/cli.js",
   "files": [

package/src/adapters/base.js

@@ -68,13 +68,9 @@ class BaseAdapter {
     fs.mkdirSync(path.join(targetDir, 'sdds'), { recursive: true });
     fs.mkdirSync(path.join(targetDir, 'tools'), { recursive: true });
 
-    // 2. Gitignore sdds/*
-    const gitignorePath = path.join(targetDir, '.gitignore');
-    let gitignore = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf-8') : '';
-    if (!gitignore.includes('sdds/*')) {
-      gitignore += '\n\n# Local Spec-Driven Development (SDD) files\nsdds/*\n!sdds/.gitkeep\nopenspec/*\n!openspec/.gitkeep\n.ruff_cache/\n';
-      fs.writeFileSync(gitignorePath, gitignore, 'utf-8');
-    }
+    // 2. Gitignore local SDD specs, ephemeral artifacts, and AI IDE mirrors
+    const { ensureGitignoreEntries } = require('../gitignore');
+    ensureGitignoreEntries(targetDir);
     fs.writeFileSync(path.join(targetDir, 'sdds', '.gitkeep'), '', 'utf-8');
 
     // 3. Write AGENTS.md

package/src/catalog.js

@@ -28,152 +28,152 @@ const SAFEGUARD_CATALOG = [
   { name: 'scan_secrets', labels: ['scan_secrets', 'scan_secrets.js', 'scan_secrets.py'],
     checks: 'Secret & private-key leak scan', verify: ['verify_secret_leaks', 'verify_no_hardcoded_secrets'],
     applies_when: 'always', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'scan_secrets.js+scan_secrets.py', manifest: true, planned: false },
+    phase: 'audit', file: 'scan_secrets.js+scan_secrets.py', manifest: true, planned: false, lens: 'security' },
 
   { name: 'check_architecture', labels: ['check_architecture', 'check_architecture.js', 'check_architecture.py'],
     checks: 'Clean Architecture layer / server-component boundaries', verify: ['verify_architecture_layers', 'verify_server_component_boundaries'],
     applies_when: 'frontend,backend', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_architecture.js+check_architecture.py', manifest: true, planned: false },
+    phase: 'audit', file: 'check_architecture.js+check_architecture.py', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'check_custom', labels: ['check_custom', 'check_custom.js', 'check_custom.py'],
     checks: 'User-defined regex rules from `.clc-forge.yml`', verify: ['verify_custom_rules', 'verify_user_defined_regex_rules'],
     applies_when: 'always', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_custom.js+check_custom.py', manifest: true, planned: false },
+    phase: 'audit', file: 'check_custom.js+check_custom.py', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'check_a11y', labels: ['check_a11y', 'check_a11y.js'],
     checks: 'ARIA + alt accessibility', verify: ['verify_a11y', 'verify_accessibility'],
     applies_when: 'frontend', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_a11y.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_a11y.js', manifest: true, planned: false, lens: 'correctness' },
 
   { name: 'check_ui_reuse', labels: ['check_ui_reuse', 'check_ui_reuse.js'],
     checks: 'UI primitive reuse from components/ui/', verify: ['verify_ui_reuse', 'verify_component_reuse'],
     applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_ui_reuse.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_ui_reuse.js', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'check_performance', labels: ['check_performance', 'check_performance.js'],
     checks: 'next/image + tree-shaking', verify: ['verify_performance', 'verify_image_optimization'],
     applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_performance.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_performance.js', manifest: true, planned: false, lens: 'performance' },
 
   { name: 'check_responsive', labels: ['check_responsive', 'check_responsive.js'],
     checks: 'Mobile-first responsiveness, fixed-width overflow & touch target size', verify: ['verify_responsive', 'verify_mobile_adaptability'],
     applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_responsive.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_responsive.js', manifest: true, planned: false, lens: 'performance' },
 
   { name: 'check_seo', labels: ['check_seo', 'check_seo.js'],
     checks: 'SEO metadata, OpenGraph, GEO tags, semantic HTML & LCP priority', verify: ['verify_seo', 'verify_geo_metadata', 'verify_core_web_vitals'],
     applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_seo.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_seo.js', manifest: true, planned: false, lens: 'performance' },
 
   { name: 'check_storybook', labels: ['check_storybook', 'check_storybook.js'],
     checks: 'Storybook coverage (`.stories.tsx`)', verify: ['verify_storybook_coverage'],
     applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_storybook.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_storybook.js', manifest: true, planned: false, lens: 'performance' },
 
   { name: 'check_api_contracts', labels: ['check_api_contracts', 'check_api_contracts.js'],
     checks: 'Zod response-schema parsing', verify: ['verify_api_contracts', 'verify_response_schemas'],
     applies_when: 'frontend', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_api_contracts.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_api_contracts.js', manifest: true, planned: false, lens: 'correctness' },
 
   { name: 'check_migrations', labels: ['check_migrations', 'check_migrations.py'],
     checks: 'Alembic/Django migration idempotency', verify: ['verify_migration_idempotency'],
     applies_when: 'backend,fastapi,django', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_migrations.py', manifest: true, planned: false },
+    phase: 'audit', file: 'check_migrations.py', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'verify_tdd', labels: ['verify_tdd', 'verify_tdd.py'],
     checks: 'Real red→green TDD validation', verify: ['verify_tdd_red_green', 'verify_tdd_evidence'],
     applies_when: 'backend', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'verify_tdd.py', manifest: false, planned: false },
+    phase: 'audit', file: 'verify_tdd.py', manifest: false, planned: false, lens: 'correctness' },
 
   { name: 'check_scope', labels: ['check_scope', 'check_scope.py'],
     checks: 'git-diff vs SDD-authorization scope guardrail', verify: ['verify_scope_authorization', 'verify_sdd_scope'],
     applies_when: 'always', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_scope.py', manifest: false, planned: false },
+    phase: 'audit', file: 'check_scope.py', manifest: false, planned: false, lens: 'correctness' },
 
   { name: 'celery_guard', labels: ['celery_guard', 'celery_guard.py'],
     checks: 'Broker URL exposure, ignore_result, result backend', verify: ['verify_celery_broker_config'],
     applies_when: 'celery', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'celery_guard.py', manifest: true, planned: false },
+    phase: 'audit', file: 'celery_guard.py', manifest: true, planned: false, lens: 'security' },
 
   { name: 'redis_guard', labels: ['redis_guard', 'redis_guard.py'],
     checks: 'decode_responses, connect timeout, hardcoded URLs', verify: ['verify_redis_config'],
     applies_when: 'redis', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'redis_guard.py', manifest: true, planned: false },
+    phase: 'audit', file: 'redis_guard.py', manifest: true, planned: false, lens: 'security' },
 
   { name: 'postgres_guard', labels: ['postgres_guard', 'postgres_guard.py'],
     checks: 'Raw SQL string formatting, hstore misuse', verify: ['verify_postgres_sql_usage'],
     applies_when: 'postgresql', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'postgres_guard.py', manifest: true, planned: false },
+    phase: 'audit', file: 'postgres_guard.py', manifest: true, planned: false, lens: 'security' },
 
   { name: 'docker_guard', labels: ['docker_guard', 'docker_guard.py'],
     checks: 'Non-root USER, ENV secrets, missing HEALTHCHECK', verify: ['verify_dockerfile_security'],
     applies_when: 'docker', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'docker_guard.py', manifest: true, planned: false },
+    phase: 'audit', file: 'docker_guard.py', manifest: true, planned: false, lens: 'security' },
 
   { name: 'check_symlinks', labels: ['check_symlinks', 'check_symlinks.js'],
     checks: 'AI IDE symlinks and rule mirror verification', verify: ['verify_symlinks', 'verify_rule_mirrors'],
     applies_when: 'agent-os', severity: 'error', gate_mode: 'hard', config_keys: ['scope'],
-    phase: 'audit', file: 'check_symlinks.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_symlinks.js', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'check_hitl', labels: ['check_hitl', 'check_hitl.js'],
     checks: 'Human-in-the-Loop review checkpoint validator in subagent skills', verify: ['verify_hitl', 'verify_human_review_checkpoints'],
     applies_when: 'agent-os', severity: 'error', gate_mode: 'hard', config_keys: ['scope'],
-    phase: 'audit', file: 'check_hitl.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_hitl.js', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'check_domain_data', labels: ['check_domain_data', 'check_domain_data.js'],
     checks: 'Domain deliverables schema and clean state integrity', verify: ['verify_domain_data', 'verify_clean_state_metrics'],
     applies_when: 'agent-os', severity: 'error', gate_mode: 'hard', config_keys: ['scope'],
-    phase: 'audit', file: 'check_domain_data.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_domain_data.js', manifest: true, planned: false, lens: 'architecture' },
 
   { name: 'check_test_calendar_sync', labels: ['check_test_calendar_sync', 'check_test_calendar_sync.js'],
     checks: 'Test calendar harness synchronization and parity check', verify: ['verify_calendar_sync', 'verify_test_calendar_sync'],
     applies_when: 'agent-os', severity: 'error', gate_mode: 'hard', config_keys: ['scope'],
-    phase: 'audit', file: 'check_test_calendar_sync.js', manifest: true, planned: false },
+    phase: 'audit', file: 'check_test_calendar_sync.js', manifest: true, planned: false, lens: 'performance' },
 
   { name: 'ruff', labels: ['ruff'],
     checks: 'Python AST linter (external CLI)', verify: ['verify_python_lint'],
     applies_when: 'backend', severity: 'warning', gate_mode: 'advisory', config_keys: [],
-    phase: 'test', file: null, manifest: true, planned: false },
+    phase: 'test', file: null, manifest: true, planned: false, lens: 'correctness' },
 
   { name: 'pytest', labels: ['pytest'],
     checks: 'Test runner (external CLI)', verify: ['verify_test_coverage'],
     applies_when: 'backend', severity: 'warning', gate_mode: 'advisory', config_keys: [],
-    phase: 'test', file: null, manifest: true, planned: false },
+    phase: 'test', file: null, manifest: true, planned: false, lens: 'correctness' },
 
   { name: 'tsc', labels: ['tsc'],
     checks: 'TypeScript typecheck (external)', verify: ['verify_typescript_types'],
     applies_when: 'frontend', severity: 'error', gate_mode: 'hard', config_keys: [],
-    phase: 'test', file: null, manifest: true, planned: false },
+    phase: 'test', file: null, manifest: true, planned: false, lens: 'correctness' },
 
   { name: 'lint', labels: ['lint', 'lint-staged'],
     checks: 'lint-staged (external)', verify: ['verify_lint_staged'],
     applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: [],
-    phase: 'test', file: null, manifest: true, planned: false },
+    phase: 'test', file: null, manifest: true, planned: false, lens: 'correctness' },
 
   { name: 'graphify', labels: ['graphify'],
     checks: 'Memory graph (external, graceful-skip)', verify: ['verify_memory_graph'],
     applies_when: 'always', severity: 'warning', gate_mode: 'advisory', config_keys: [],
-    phase: 'review', file: null, manifest: false, planned: false },
+    phase: 'review', file: null, manifest: false, planned: false, lens: 'architecture' },
 
   { name: 'gentle_ai_review', labels: ['gentle_ai_review', 'gentle-ai'],
     checks: 'Native bounded review gate (external, graceful-skip)', verify: ['verify_rdd_review_gate'],
     applies_when: 'always', severity: 'error', gate_mode: 'hard', config_keys: [],
-    phase: 'review', file: null, manifest: false, planned: false },
+    phase: 'review', file: null, manifest: false, planned: false, lens: 'architecture' },
 
   { name: 'check_openapi_drift', labels: ['check_openapi_drift', 'check_openapi_drift.py'],
     checks: 'FastAPI OpenAPI schema drift vs app routes', verify: ['verify_openapi_drift'],
     applies_when: 'fastapi', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_openapi_drift.py', manifest: true, planned: true },
+    phase: 'audit', file: 'check_openapi_drift.py', manifest: true, planned: true, lens: 'correctness' },
 
   { name: 'check_db_efficiency', labels: ['check_db_efficiency', 'check_db_efficiency.py'],
     checks: 'ORM N+1 / select_related / prefetch_related', verify: ['verify_db_efficiency', 'verify_no_n_plus_1'],
     applies_when: 'django|sqlalchemy', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_db_efficiency.py', manifest: true, planned: false },
+    phase: 'audit', file: 'check_db_efficiency.py', manifest: true, planned: false, lens: 'performance' },
 
   { name: 'check_observability', labels: ['check_observability', 'check_observability.py'],
     checks: 'structlog structured logging; bare print/logger ban', verify: ['verify_structured_logging'],
     applies_when: 'backend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
-    phase: 'audit', file: 'check_observability.py', manifest: true, planned: true },
+    phase: 'audit', file: 'check_observability.py', manifest: true, planned: true, lens: 'performance' },
 ];
 
 // Freeze the registry so config validation and generation can rely on it.
@@ -195,6 +195,9 @@ const VALID_APPLIES_WHEN = [
   'agent-os',
 ];
 
+/** Canonical 4 RDD Lenses */
+const VALID_LENSES = ['correctness', 'security', 'architecture', 'performance'];
+
 /** Normalize an input label for catalog lookup. */
 function normalizeLabel(name) {
   return typeof name === 'string' ? name.trim().toLowerCase() : '';
@@ -226,13 +229,21 @@ function gateFor(name) {
   return entry ? entry.gate_mode : null;
 }
 
+/** Canonical RDD review lens for a guard name/label; null when unknown. */
+function lensFor(name) {
+  const entry = applyTo(name);
+  return entry ? entry.lens : null;
+}
+
 module.exports = {
   SAFEGUARD_CATALOG,
   VALID_SEVERITIES,
   VALID_GATE_MODES,
   VALID_PHASES,
   VALID_APPLIES_WHEN,
+  VALID_LENSES,
   applyTo,
   severityFor,
   gateFor,
+  lensFor,
 };

package/src/generator.js

@@ -330,12 +330,8 @@ function generateHarness(targetDir, configOrNull) {
     fs.mkdirSync(path.join(targetDir, 'sdds'), { recursive: true });
     fs.mkdirSync(path.join(targetDir, 'tools'), { recursive: true });
 
-    const gitignorePath = path.join(targetDir, '.gitignore');
-    let gitignoreContent = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf-8') : '';
-    if (!gitignoreContent.includes('sdds/*')) {
-      gitignoreContent += '\n\n# Local Spec-Driven Development (SDD) files\nsdds/*\n!sdds/.gitkeep\nopenspec/*\n!openspec/.gitkeep\n.ruff_cache/\n';
-      fs.writeFileSync(gitignorePath, gitignoreContent, 'utf-8');
-    }
+    const { ensureGitignoreEntries } = require('./gitignore');
+    ensureGitignoreEntries(targetDir);
     fs.writeFileSync(path.join(targetDir, 'sdds', '.gitkeep'), '', 'utf-8');
 
     const agentsContent = `# CLC Kernel ${config.framework || 'Generic'} (${(config.projectType || 'unknown').toUpperCase()}) — AGENTS

package/src/gitignore.js

@@ -0,0 +1,98 @@
+/**
+ * CLC Kernel — Gitignore Provisioning Engine
+ * Ensures AI IDE mirror symlinks, local SDD specs, and ephemeral runtime artifacts
+ * are safely ignored in consumer repositories to preserve AGENTS.md as the SSOT.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MANAGED_GITIGNORE_SECTIONS = [
+  {
+    header: '# CLC Kernel: Local AI IDE Mirror Symlinks (SSOT: AGENTS.md)',
+    entries: [
+      'CLAUDE.md',
+      'GEMINI.md',
+      '.cursorrules',
+      '.windsurfrules',
+      '.cursor/',
+      '.antigravity/',
+      '.github/copilot-instructions.md',
+    ],
+  },
+  {
+    header: '# CLC Kernel: CLI Agent Skills & Playbooks',
+    entries: [
+      '.agents/skills/clckernel_cli/',
+      '.agents/skills/clc_forge_cli/',
+    ],
+  },
+  {
+    header: '# CLC Kernel: Local SDD Specs & Ephemeral Harness Artifacts',
+    entries: [
+      'sdds/*',
+      '!sdds/.gitkeep',
+      'openspec/*',
+      '!openspec/.gitkeep',
+      '.clckernel.resolved.json',
+      '.clc-forge.resolved.json',
+      '.husky/_/',
+      '.ruff_cache/',
+    ],
+  },
+];
+
+/**
+ * Idempotently appends missing CLC Kernel entries to target project's .gitignore.
+ *
+ * @param {string} targetDir - Target project root
+ * @returns {boolean} True if .gitignore was created or modified, false if already complete.
+ */
+function ensureGitignoreEntries(targetDir) {
+  const gitignorePath = path.join(targetDir, '.gitignore');
+  let currentContent = '';
+  if (fs.existsSync(gitignorePath)) {
+    try {
+      currentContent = fs.readFileSync(gitignorePath, 'utf-8');
+    } catch (e) {
+      currentContent = '';
+    }
+  }
+
+  const existingLines = new Set(
+    currentContent
+      .split('\n')
+      .map(line => line.trim())
+      .filter(line => line.length > 0)
+  );
+
+  const sectionsToAppend = [];
+
+  for (const section of MANAGED_GITIGNORE_SECTIONS) {
+    const missingEntries = section.entries.filter(entry => !existingLines.has(entry.trim()));
+    if (missingEntries.length > 0) {
+      sectionsToAppend.push(`${section.header}\n${missingEntries.join('\n')}`);
+    }
+  }
+
+  if (sectionsToAppend.length === 0) {
+    return false;
+  }
+
+  let newContent = currentContent;
+  if (newContent.length > 0 && !newContent.endsWith('\n')) {
+    newContent += '\n';
+  }
+  if (newContent.length > 0) {
+    newContent += '\n';
+  }
+  newContent += sectionsToAppend.join('\n\n') + '\n';
+
+  fs.writeFileSync(gitignorePath, newContent, 'utf-8');
+  return true;
+}
+
+module.exports = {
+  ensureGitignoreEntries,
+  MANAGED_GITIGNORE_SECTIONS,
+};

package/src/updater.js

@@ -32,6 +32,8 @@ function updateHarness(targetDir = process.cwd(), options = {}) {
 
   // 3. Run harness generation (refreshes tools, hooks, skills, and symlinks)
   generateHarness(resolvedDir, detected);
+  const { ensureGitignoreEntries } = require('./gitignore');
+  ensureGitignoreEntries(resolvedDir);
 
   // 4. Ensure AGENTS.md documents the update command in its command table.
   // Non-destructive: only inject into a file that already carries the CLC

package/tools/audit.js

@@ -2,7 +2,9 @@
 /**
  * Modular Audit Orchestrator — JS
  * Discovers check_*.js guard scripts at runtime, runs each with graceful
- * degradation, and generates an English audit report (05-audit-report.md).
+ * degradation, categorizes results into the 4 Canonical RDD Lenses,
+ * and generates both an English audit report (05-audit-report.md) and
+ * an immutable, machine-readable audit receipt (audit-receipt.json).
  * Self-contained: uses only Node.js built-ins.
  */
 
@@ -11,10 +13,59 @@ const path = require('path');
 
 const REPO_ROOT = path.resolve(__dirname, '..');
 
+// ── 4 Canonical RDD Lenses Mapping ──────────────────────────────────────────
+
+const LENS_MAP = {
+  // Correctness
+  verify_tdd: 'correctness',
+  check_scope: 'correctness',
+  check_a11y: 'correctness',
+  check_api_contracts: 'correctness',
+  check_openapi_drift: 'correctness',
+  pytest: 'correctness',
+  tsc: 'correctness',
+  lint: 'correctness',
+  ruff: 'correctness',
+  // Security
+  scan_secrets: 'security',
+  docker_guard: 'security',
+  redis_guard: 'security',
+  celery_guard: 'security',
+  postgres_guard: 'security',
+  // Architecture
+  check_architecture: 'architecture',
+  check_custom: 'architecture',
+  check_ui_reuse: 'architecture',
+  check_symlinks: 'architecture',
+  check_hitl: 'architecture',
+  check_domain_data: 'architecture',
+  check_migrations: 'architecture',
+  graphify: 'architecture',
+  gentle_ai_review: 'architecture',
+  // Performance
+  check_db_efficiency: 'performance',
+  check_performance: 'performance',
+  check_seo: 'performance',
+  check_responsive: 'performance',
+  check_storybook: 'performance',
+  check_test_calendar_sync: 'performance',
+  check_observability: 'performance',
+};
+
+function getLensForGuard(guardName) {
+  try {
+    const { lensFor } = require('../src/catalog');
+    const lens = lensFor(guardName);
+    if (lens) return lens;
+  } catch {}
+  return LENS_MAP[guardName] || 'architecture';
+}
+
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-function getActiveSddDir() {
-  const sddsDir = path.join(REPO_ROOT, 'sdds');
+function getActiveSddDir(baseDir) {
+  const root = baseDir || REPO_ROOT;
+  const sddsDir = path.join(root, 'sdds');
   if (!fs.existsSync(sddsDir)) {
     fs.mkdirSync(sddsDir, { recursive: true });
   }
@@ -25,7 +76,7 @@ function getActiveSddDir() {
   if (dirs.length > 0) {
     return path.join(sddsDir, dirs[0]);
   }
-  const defaultDir = path.join(sddsDir, 'frontend-audit');
+  const defaultDir = path.join(sddsDir, 'audit-run');
   fs.mkdirSync(defaultDir, { recursive: true });
   return defaultDir;
 }
@@ -34,8 +85,9 @@ function getActiveSddDir() {
  * Discover all check_*.js guard scripts in the tools/ directory.
  * Returns absolute paths sorted alphabetically for deterministic ordering.
  */
-function discoverGuards() {
-  const toolsDir = __dirname;
+function discoverGuards(toolsDirParam) {
+  const toolsDir = toolsDirParam || __dirname;
+  if (!fs.existsSync(toolsDir)) return [];
   return fs.readdirSync(toolsDir)
     .filter(f => (f.startsWith('check_') || f.startsWith('scan_')) && f.endsWith('.js') && f !== path.basename(__filename || 'audit.js'))
     .sort()
@@ -50,12 +102,13 @@ function discoverGuards() {
  */
 async function runGuard(guardPath, targetDir) {
   const guardName = path.basename(guardPath, '.js');
+  const lens = getLensForGuard(guardName);
   try {
     const mod = require(guardPath);
     const fn = typeof mod === 'function' ? mod : Object.values(mod)[0];
     if (typeof fn !== 'function') {
       return {
-        exitCode: 0, skipped: true, name: guardName,
+        exitCode: 0, skipped: true, name: guardName, lens,
         data: { message: `Guard ${guardName} does not export a function` },
       };
     }
@@ -65,11 +118,12 @@ async function runGuard(guardPath, targetDir) {
       exitCode: result.exitCode || 0,
       skipped: Boolean(result.skipped),
       name: result.name || guardName,
+      lens,
       data: result.data || result,
     };
   } catch (e) {
     return {
-      exitCode: 0, skipped: true, name: guardName,
+      exitCode: 0, skipped: true, name: guardName, lens,
       data: { message: `Guard unavailable: ${e.message}` },
     };
   }
@@ -84,8 +138,9 @@ function formatGuardSection(name, result) {
   const lines = [];
   const icon = result.skipped ? '⏭️' : result.exitCode === 0 ? '✅' : '❌';
   const status = result.skipped ? 'SKIPPED' : result.exitCode === 0 ? 'PASSED' : 'FAILED';
+  const lensBadge = (result.lens || 'architecture').toUpperCase();
 
-  lines.push(`### ${icon} ${name.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase())} — ${status}`);
+  lines.push(`### ${icon} ${name.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase())} [${lensBadge}] — ${status}`);
   lines.push('');
 
   if (result.skipped) {
@@ -96,15 +151,21 @@ function formatGuardSection(name, result) {
     lines.push(`> ${result.data?.message || 'Issues found'}`);
     lines.push('');
     const violations = result.data?.violations || result.data?.findings || {};
-    const files = Object.keys(violations);
-    if (files.length > 0) {
-      for (const file of files) {
-        const items = violations[file];
-        for (const item of items) {
-          const loc = item.lineNo ? ` (line ${item.lineNo})` : '';
-          const label = item.label || item.rule || item.rule || item.module || '';
-          const msg = item.message || item.reason || '';
-          lines.push(`- \`${file}\`${loc}: ${label ? `[${label}] ` : ''}${msg}`);
+    if (Array.isArray(violations)) {
+      for (const item of violations) {
+        lines.push(`- ${item.file ? `\`${item.file}\`: ` : ''}${item.message || item.reason || JSON.stringify(item)}`);
+      }
+    } else {
+      const files = Object.keys(violations);
+      if (files.length > 0) {
+        for (const file of files) {
+          const items = violations[file];
+          for (const item of items) {
+            const loc = item.lineNo ? ` (line ${item.lineNo})` : '';
+            const label = item.label || item.rule || item.module || '';
+            const msg = item.message || item.reason || '';
+            lines.push(`- \`${file}\`${loc}: ${label ? `[${label}] ` : ''}${msg}`);
+          }
         }
       }
     }
@@ -127,8 +188,8 @@ function generateReport(results, sddDir) {
 
   sections.push(`# Code Audit Report: ${taskName}`);
   sections.push('');
-  sections.push('> **Note for reviewer:** This report summarizes security, architecture, accessibility,');
-  sections.push('> API contracts, performance, UI reuse, and testing coverage to facilitate review.');
+  sections.push('> **Review-Driven Development (RDD) Report:**');
+  sections.push('> Segmented across the 4 Canonical Review Lenses (Correctness, Security, Architecture, Performance).');
   sections.push('');
   sections.push('---');
   sections.push('');
@@ -144,9 +205,26 @@ function generateReport(results, sddDir) {
   sections.push('---');
   sections.push('');
 
-  for (const result of results) {
-    sections.push(formatGuardSection(result.name, result));
+  const lenses = ['correctness', 'security', 'architecture', 'performance'];
+  const lensHeaders = {
+    correctness: '## 🎯 Correctness Lens',
+    security: '## 🛡️ Security Lens',
+    architecture: '## 🏛️ Architecture Lens',
+    performance: '## ⚡ Performance Lens',
+  };
+
+  for (const lens of lenses) {
+    sections.push(lensHeaders[lens]);
     sections.push('');
+    const lensResults = results.filter(r => r.lens === lens);
+    if (lensResults.length === 0) {
+      sections.push('_No guards registered for this lens._\n');
+    } else {
+      for (const result of lensResults) {
+        sections.push(formatGuardSection(result.name, result));
+        sections.push('');
+      }
+    }
     sections.push('---');
     sections.push('');
   }
@@ -154,33 +232,107 @@ function generateReport(results, sddDir) {
   return sections.join('\n');
 }
 
+/**
+ * Generate an immutable machine-readable audit receipt (audit-receipt.json).
+ */
+function generateReceipt(results, targetDir) {
+  const lenses = ['correctness', 'security', 'architecture', 'performance'];
+  const lensSummary = {};
+
+  let hasFailure = false;
+  for (const lens of lenses) {
+    const lensResults = results.filter(r => r.lens === lens);
+    const passed = lensResults.filter(r => !r.skipped && r.exitCode === 0).length;
+    const failed = lensResults.filter(r => !r.skipped && r.exitCode !== 0).length;
+    const skipped = lensResults.filter(r => r.skipped).length;
+    if (failed > 0) hasFailure = true;
+
+    lensSummary[lens] = {
+      status: failed > 0 ? 'FAILED' : 'PASSED',
+      passed,
+      failed,
+      skipped,
+    };
+  }
+
+  let commitHash = 'UNKNOWN';
+  let gentleAiDetected = false;
+  try {
+    const { execSync } = require('child_process');
+    commitHash = execSync('git rev-parse HEAD', { cwd: targetDir, stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' }).trim();
+  } catch {}
+
+  try {
+    const { execSync } = require('child_process');
+    execSync('which gentle-ai', { stdio: 'ignore' });
+    gentleAiDetected = true;
+  } catch {}
+
+  return {
+    $schema: 'https://clckernel.dev/schemas/audit-receipt.v1.json',
+    contract: 'clckernel.audit-receipt/v1',
+    timestamp: new Date().toISOString(),
+    commitHash,
+    verdict: hasFailure ? 'FAILED' : 'PASSED',
+    lenses: lensSummary,
+    generator: 'clckernel',
+    gentle_ai: {
+      compatible: true,
+      rdd_ready: true,
+      cli_installed: gentleAiDetected,
+    },
+  };
+}
+
 // ── Console Summary ──────────────────────────────────────────────────────────
 
-function printSummary(results, reportPath) {
+function printSummary(results, reportPath, receiptPath) {
   console.log('\n=================================================================');
-  console.log('  CLC FORGE — EDUCATIONAL AUDIT SUMMARY');
+  console.log('  CLC KERNEL — 4-LENS RDD AUDIT SUMMARY');
   console.log('=================================================================\n');
 
-  for (const result of results) {
-    const icon = result.skipped ? '⏭️' : result.exitCode === 0 ? '✅' : '❌';
-    const label = result.name.replace(/_/g, ' ');
-    const msg = result.data?.message || '';
-    console.log(`  ${icon} ${label}: ${msg}`);
+  const lenses = ['correctness', 'security', 'architecture', 'performance'];
+  const lensLabels = {
+    correctness: '🎯 CORRECTNESS LENS',
+    security: '🛡️ SECURITY LENS',
+    architecture: '🏛️ ARCHITECTURE LENS',
+    performance: '⚡ PERFORMANCE LENS',
+  };
+
+  for (const lens of lenses) {
+    const lensResults = results.filter(r => r.lens === lens);
+    console.log(`  ${lensLabels[lens]}:`);
+    if (lensResults.length === 0) {
+      console.log('     — No guards active for this lens');
+    } else {
+      for (const result of lensResults) {
+        const icon = result.skipped ? '⏭️' : result.exitCode === 0 ? '✅' : '❌';
+        const label = result.name.replace(/_/g, ' ');
+        const msg = result.data?.message || (result.exitCode === 0 ? 'Passed' : 'Failed');
+        console.log(`     ${icon} ${label}: ${msg}`);
+      }
+    }
+    console.log('');
   }
 
-  console.log(`\n📄 Full report: ${reportPath}`);
+  console.log(`📄 Full report: ${reportPath}`);
+  if (receiptPath) {
+    console.log(`🧾 Audit receipt: ${receiptPath}`);
+  }
   console.log('=================================================================\n');
 }
 
 // ── Main ─────────────────────────────────────────────────────────────────────
 
 async function main(targetDir) {
-  const dir = targetDir || process.cwd();
-  const sddDir = getActiveSddDir();
+  const dir = targetDir ? path.resolve(targetDir) : process.cwd();
+  const sddDir = getActiveSddDir(dir);
 
-  console.log('\nRunning CLC Forge audit...\n');
+  console.log('\nRunning CLC Kernel audit...\n');
 
-  const guardPaths = discoverGuards();
+  const targetTools = path.join(dir, 'tools');
+  const toolsDir = fs.existsSync(targetTools) ? targetTools : __dirname;
+  const guardPaths = discoverGuards(toolsDir);
 
   if (guardPaths.length === 0) {
     console.log('No guard tools found in tools/. Nothing to audit.');
@@ -200,20 +352,27 @@ async function main(targetDir) {
   const reportPath = path.join(sddDir, '05-audit-report.md');
   fs.writeFileSync(reportPath, reportContent, 'utf-8');
 
+  // Generate receipt
+  const receipt = generateReceipt(results, dir);
+  const receiptPath = path.join(sddDir, 'audit-receipt.json');
+  fs.writeFileSync(receiptPath, JSON.stringify(receipt, null, 2) + '\n', 'utf-8');
+
   // Print summary
-  printSummary(results, reportPath);
+  printSummary(results, reportPath, receiptPath);
 
   // Exit with failure if any guard failed (not skipped)
   const hasFailure = results.some(r => !r.skipped && r.exitCode !== 0);
-  process.exit(hasFailure ? 1 : 0);
+  if (hasFailure) {
+    process.exit(1);
+  }
 }
 
 // Support both require() and direct execution
 if (require.main === module) {
   main(process.argv[2]).catch(err => {
     console.error(`Audit orchestrator error: ${err.message}`);
-    process.exit(0); // Graceful degradation
+    process.exit(1);
   });
 }
 
-module.exports = { main, getActiveSddDir, discoverGuards, runGuard };
+module.exports = { main, getActiveSddDir, discoverGuards, runGuard, generateReceipt };

package/tools/audit.py

@@ -17,6 +17,48 @@ import traceback
 
 REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
 
+# ── 4 Canonical RDD Lenses Mapping ──────────────────────────────────────────
+
+LENS_MAP = {
+    # Correctness
+    "verify_tdd": "correctness",
+    "check_scope": "correctness",
+    "check_a11y": "correctness",
+    "check_api_contracts": "correctness",
+    "check_openapi_drift": "correctness",
+    "pytest": "correctness",
+    "tsc": "correctness",
+    "lint": "correctness",
+    "ruff": "correctness",
+    # Security
+    "scan_secrets": "security",
+    "docker_guard": "security",
+    "redis_guard": "security",
+    "celery_guard": "security",
+    "postgres_guard": "security",
+    # Architecture
+    "check_architecture": "architecture",
+    "check_custom": "architecture",
+    "check_ui_reuse": "architecture",
+    "check_symlinks": "architecture",
+    "check_hitl": "architecture",
+    "check_domain_data": "architecture",
+    "check_migrations": "architecture",
+    "graphify": "architecture",
+    "gentle_ai_review": "architecture",
+    # Performance
+    "check_db_efficiency": "performance",
+    "check_performance": "performance",
+    "check_seo": "performance",
+    "check_responsive": "performance",
+    "check_storybook": "performance",
+    "check_test_calendar_sync": "performance",
+    "check_observability": "performance",
+}
+
+def get_lens(guard_name: str) -> str:
+    return LENS_MAP.get(guard_name, "architecture")
+
 
 # ── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -87,12 +129,14 @@ def run_guard(guard_path: pathlib.Path, target_dir: str) -> dict:
             "exit_code": result.get("exit_code", 0),
             "skipped": bool(result.get("skipped", False)),
             "name": result.get("name", guard_name),
+            "lens": get_lens(guard_name),
             "data": result.get("data", result),
         }
 
     except Exception as exc:
         return {
             "exit_code": 0, "skipped": True, "name": guard_name,
+            "lens": get_lens(guard_name),
             "data": {"message": f"Guard unavailable: {exc}"},
         }
 
@@ -151,7 +195,7 @@ def _format_guard_section(name: str, result: dict) -> str:
 
 
 def generate_report(results: list[dict], sdd_dir: pathlib.Path) -> str:
-    """Generate the 05-audit-report.md from aggregated guard results."""
+    """Generate the 05-audit-report.md from aggregated guard results grouped by 4 RDD lenses."""
     task_name = sdd_dir.name
     passed = sum(1 for r in results if not r.get("skipped") and r.get("exit_code") == 0)
     failed = sum(1 for r in results if not r.get("skipped") and r.get("exit_code") != 0)
@@ -161,8 +205,8 @@ def generate_report(results: list[dict], sdd_dir: pathlib.Path) -> str:
     sections: list[str] = []
     sections.append(f"# Code Audit Report: {task_name}")
     sections.append("")
-    sections.append("> **Note for reviewer:** This report summarizes security, architecture,")
-    sections.append("> scope, migration safety, and TDD coverage to facilitate code review.")
+    sections.append("> **Review-Driven Development (RDD) Report:**")
+    sections.append("> Segmented across the 4 Canonical Review Lenses (Correctness, Security, Architecture, Performance).")
     sections.append("")
     sections.append("---")
     sections.append("")
@@ -178,39 +222,116 @@ def generate_report(results: list[dict], sdd_dir: pathlib.Path) -> str:
     sections.append("---")
     sections.append("")
 
-    for result in results:
-        sections.append(_format_guard_section(result.get("name", "unknown"), result))
+    lenses = ["correctness", "security", "architecture", "performance"]
+    headers = {
+        "correctness": "## 🎯 Correctness Lens",
+        "security": "## 🛡️ Security Lens",
+        "architecture": "## 🏛️ Architecture Lens",
+        "performance": "## ⚡ Performance Lens",
+    }
+
+    for lens in lenses:
+        sections.append(headers[lens])
         sections.append("")
+        lens_results = [r for r in results if r.get("lens") == lens]
+        if not lens_results:
+            sections.append("_No guards registered for this lens._\n")
+        else:
+            for result in lens_results:
+                sections.append(_format_guard_section(result.get("name", "unknown"), result))
+                sections.append("")
         sections.append("---")
         sections.append("")
 
     return "\n".join(sections)
 
 
+def generate_receipt(results: list[dict], target_dir: str) -> dict:
+    """Generate an immutable machine-readable audit receipt (audit-receipt.json)."""
+    import datetime
+
+    lenses = ["correctness", "security", "architecture", "performance"]
+    lens_summary = {}
+    has_failure = False
+
+    for lens in lenses:
+        lens_results = [r for r in results if r.get("lens") == lens]
+        passed = sum(1 for r in lens_results if not r.get("skipped") and r.get("exit_code") == 0)
+        failed = sum(1 for r in lens_results if not r.get("skipped") and r.get("exit_code") != 0)
+        skipped = sum(1 for r in lens_results if r.get("skipped"))
+        if failed > 0:
+            has_failure = True
+        lens_summary[lens] = {
+            "status": "FAILED" if failed > 0 else "PASSED",
+            "passed": passed,
+            "failed": failed,
+            "skipped": skipped,
+        }
+
+    commit_hash = "UNKNOWN"
+    try:
+        commit_hash = subprocess.check_output(
+            ["git", "rev-parse", "HEAD"],
+            cwd=target_dir,
+            stderr=subprocess.DEVNULL,
+            encoding="utf-8"
+        ).strip()
+    except Exception:
+        pass
+
+    import shutil
+    gentle_ai_detected = shutil.which("gentle-ai") is not None
+
+    return {
+        "$schema": "https://clckernel.dev/schemas/audit-receipt.v1.json",
+        "contract": "clckernel.audit-receipt/v1",
+        "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "commitHash": commit_hash,
+        "verdict": "FAILED" if has_failure else "PASSED",
+        "lenses": lens_summary,
+        "generator": "clckernel",
+        "gentle_ai": {
+            "compatible": True,
+            "rdd_ready": True,
+            "cli_installed": gentle_ai_detected,
+        },
+    }
+
+
 # ── Console Summary ──────────────────────────────────────────────────────────
 
-def print_summary(results: list[dict], report_path: pathlib.Path) -> None:
+def print_summary(results: list[dict], report_path: pathlib.Path, receipt_path: pathlib.Path | None = None) -> None:
     """Print an educational summary to the terminal."""
     print("\n" + "=" * 65)
-    print("  CLC FORGE \u2014 EDUCATIONAL AUDIT SUMMARY")
+    print("  CLC KERNEL — 4-LENS RDD AUDIT SUMMARY")
     print("=" * 65 + "\n")
 
-    for result in results:
-        skipped = result.get("skipped", False)
-        exit_code = result.get("exit_code", 0)
-        name = result.get("name", "unknown").replace("_", " ")
-        msg = result.get("data", {}).get("message", "")
-
-        if skipped:
-            icon = "\u23ed\ufe0f"
-        elif exit_code == 0:
-            icon = "\u2705"
+    lenses = ["correctness", "security", "architecture", "performance"]
+    labels = {
+        "correctness": "🎯 CORRECTNESS LENS",
+        "security": "🛡️ SECURITY LENS",
+        "architecture": "🏛️ ARCHITECTURE LENS",
+        "performance": "⚡ PERFORMANCE LENS",
+    }
+
+    for lens in lenses:
+        lens_results = [r for r in results if r.get("lens") == lens]
+        print(f"  {labels[lens]}:")
+        if not lens_results:
+            print("     — No guards active for this lens")
         else:
-            icon = "\u274c"
-
-        print(f"  {icon} {name}: {msg}")
-
-    print(f"\n  Report: {report_path}")
+            for result in lens_results:
+                skipped = result.get("skipped", False)
+                exit_code = result.get("exit_code", 0)
+                name = result.get("name", "unknown").replace("_", " ")
+                msg = result.get("data", {}).get("message", "Passed" if exit_code == 0 else "Failed")
+                icon = "⏭️" if skipped else ("✅" if exit_code == 0 else "❌")
+                print(f"     {icon} {name}: {msg}")
+        print("")
+
+    print(f"📄 Full report: {report_path}")
+    if receipt_path:
+        print(f"🧾 Audit receipt: {receipt_path}")
     print("=" * 65 + "\n")
 
 
@@ -229,7 +350,7 @@ def main(target_dir: str | None = None) -> int:
         sdd_dir = sdds_dir / "audit-run"
         sdd_dir.mkdir(parents=True, exist_ok=True)
 
-    print(f"\nRunning CLC Forge audit for: {sdd_dir.name}\n")
+    print(f"\nRunning CLC Kernel audit for: {sdd_dir.name}\n")
 
     guard_paths = discover_guards(tools_dir)
 
@@ -253,8 +374,13 @@ def main(target_dir: str | None = None) -> int:
     report_path = sdd_dir / "05-audit-report.md"
     report_path.write_text(report_content, encoding="utf-8")
 
+    # Generate and write receipt
+    receipt = generate_receipt(results, dir_path)
+    receipt_path = sdd_dir / "audit-receipt.json"
+    receipt_path.write_text(json.dumps(receipt, indent=2) + "\n", encoding="utf-8")
+
     # Print summary
-    print_summary(results, report_path)
+    print_summary(results, report_path, receipt_path)
 
     # Exit with failure if any guard failed (not skipped)
     has_failure = any(
@@ -270,4 +396,4 @@ if __name__ == "__main__":
         sys.exit(main(target))
     except Exception:
         traceback.print_exc()
-        sys.exit(0)  # Graceful degradation
+        sys.exit(1)