clckernel 1.2.9 → 1.2.11

package/README.es.md

@@ -22,6 +22,7 @@ Los agentes de programación con IA (Cursor, Claude Code, Windsurf, Copilot) cod
 - [🏛️ El Proceso Unificado de IA (AIUP)](#️-el-proceso-unificado-de-ia-aiup)
 - [⚡ Guía Paso a Paso (Ciclo Completo)](#-guía-paso-a-paso-ciclo-completo)
 - [🎮 Interfaz Universal de Comandos](#-interfaz-universal-de-comandos)
+- [🔄 Actualización de Proyectos Existentes](#-actualización-de-proyectos-existentes)
 - [🌐 Ecosistemas Soportados y Arquetipos](#-ecosistemas-soportados-y-arquetipos)
 - [🧩 Herramientas Complementarias (Opcionales)](#-herramientas-complementarias-opcionales)
 - [📄 Licencia](#-licencia)
@@ -123,10 +124,34 @@ CLC Kernel provee una gramática de comandos determinista soportada de forma nat
 | `clckernel doctor` | Diagnóstico | Valida hooks pre-commit de Git, symlinks espejo para IDEs e integridad del motor AST. |
 | `clckernel commit <mensaje>` | Control de Versiones | Auditoría pre-flight, verificación de scope diff vs SDD y commit con Conventional Commits (cero atribución de IA). |
 | `clckernel guard create <nombre>` | Salvaguardas | Genera el scaffold de un nuevo script de guard AST en el lenguaje nativo del stack en `tools/guards/`. |
+| `clckernel update` | Mantenimiento | Actualización no destructiva: refresca herramientas core, skills y symlinks de IDEs sin sobreescribir SDDs, guards personalizados ni `.clckernel.yaml`. |
 | `clckernel start` | Configuración | Detecta el stack automáticamente, propone el ciclo de vida AIUP y genera `.clckernel.yaml`. |
 
 ---
 
+<a id="actualizacion-de-proyectos-existentes"></a>
+## 🔄 Actualización de Proyectos Existentes (No Destructiva)
+
+Cuando se publican nuevas versiones de CLC Kernel con nuevos guards AST, playbooks actualizados o reglas optimizadas para IDEs, podés actualizar tu repositorio de forma segura sin perder tu trabajo:
+
+```bash
+npx clckernel update
+```
+O directamente desde el chat de tu agente IA:
+```bash
+clckernel update
+```
+
+### 🔒 La Garantía de Actualización No Destructiva:
+- **Refresca y Actualiza:** Orquestadores centrales (`tools/audit.js`, `tools/audit.py`), guards AST nativos, Skills de agentes (`.agents/skills/`) y symlinks de IDEs (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, Copilot, Antigravity).
+- **100% Preservado:**
+  - `sdds/`: Todas las especificaciones locales, planes y recibos de verificación permanecen intactos.
+  - `tools/guards/`: Todos los guards AST personalizados creados por el equipo se conservan sin modificaciones.
+  - `.clckernel.yaml`: Todas las configuraciones y umbrales personalizados se mantienen.
+  - El código fuente de la aplicación y modelos de dominio jamás se tocan.
+
+---
+
 <a id="ecosistemas-soportados"></a>
 ## 🌐 Ecosistemas Soportados y Arquetipos
 

package/README.md

@@ -22,6 +22,7 @@ AI coding agents (Cursor, Claude Code, Windsurf, Copilot) code fast, but without
 - [🏛️ The AI Unified Process (AIUP)](#️-the-ai-unified-process-aiup)
 - [⚡ Step-by-Step Guide (Full Lifecycle)](#-step-by-step-guide-full-lifecycle)
 - [🎮 Universal Command Interface](#-universal-command-interface)
+- [🔄 Updating an Existing Project](#-updating-an-existing-project)
 - [🌐 Supported Stacks & Archetypes](#-supported-stacks--archetypes)
 - [🧩 Optional Ecosystem Companions](#-optional-ecosystem-companions)
 - [📄 License](#-license)
@@ -123,10 +124,34 @@ CLC Kernel provides a deterministic command grammar supported natively by **Clau
 | `clckernel doctor` | Diagnostics | Checks Git pre-commit hooks, IDE mirror symlinks, and AST engine integrity. |
 | `clckernel commit <message>` | Version Control | Pre-flight audit, verifies diff vs SDD scope, and commits with Conventional Commits (zero AI attribution). |
 | `clckernel guard create <name>` | Safeguards | Scaffolds a new AST guard script in the stack's native language in `tools/guards/`. |
+| `clckernel update` | Maintenance | Non-destructive update: refreshes core tools, skills & IDE symlinks without overwriting SDDs, custom guards, or `.clckernel.yaml`. |
 | `clckernel start` | Setup | Auto-detects stack, proposes AIUP lifecycle, and generates `.clckernel.yaml`. |
 
 ---
 
+<a id="updating-an-existing-project"></a>
+## 🔄 Updating an Existing Project (Non-Destructive)
+
+When new versions of CLC Kernel are released with new AST guards, upgraded playbooks, or improved IDE rules, update your project safely without losing your work:
+
+```bash
+npx clckernel update
+```
+Or from your AI agent chat:
+```bash
+clckernel update
+```
+
+### 🔒 The Non-Destructive Update Guarantee:
+- **Refreshes & Upgrades:** Core orchestrators (`tools/audit.js`, `tools/audit.py`), built-in AST guards, Agent Skills (`.agents/skills/`), and IDE symlinks (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, Copilot, Antigravity).
+- **100% Preserved:**
+  - `sdds/`: All local specifications, plans, and verification receipts remain intact.
+  - `tools/guards/`: All team-authored custom AST guards are preserved without modification.
+  - `.clckernel.yaml`: All custom thresholds and active safeguard selections are preserved.
+  - Application source code and domain models are never touched.
+
+---
+
 <a id="supported-stacks"></a>
 ## 🌐 Supported Stacks & Archetypes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clckernel",
-  "version": "1.2.9",
+  "version": "1.2.11",
   "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/agent-os.js

@@ -113,8 +113,11 @@ class AgentOSAdapter extends BaseAdapter {
   }
 
   provision(targetDir, config) {
-    // 1. Create docs/, sdds/, and tools/
-    super.provision(targetDir, config);
+    // 1. Create docs/, sdds/, and tools/. AGENTS.md is owned by this adapter
+    // (dual-layer template below), so BaseAdapter must not write its generic
+    // law file — otherwise the generic one lands first and, being present,
+    // would make the guard below skip the dual-layer render entirely.
+    super.provision(targetDir, { ...(config || {}), skipAgentsMd: true });
 
     // 2. Write Dual-Layer AGENTS.md
     const dualLayerAgents = `# Standard Operating Procedure (SOP) — AGENTS
@@ -165,6 +168,7 @@ When given a command matching \`clckernel <action>\` or \`/clckernel <action>\`,
 | \`clckernel doctor\` | Diagnostics | Check git pre-commit hooks, IDE symlinks, and AST engine integrity. |
 | \`clckernel commit <message>\` | Version Control | Run full audit, verify tests pass, ensure no changes outside SDD scope, and commit with conventional commits (never add AI attribution). |
 | \`clckernel guard create <name>\` | Safeguards | Scaffold a new AST guard in the stack's native language in \`tools/guards/\`. |
+| \`clckernel update\` | Maintenance | Non-destructive update: refresh core tools, playbooks & symlinks (preserves SDDs & custom guards). |
 | \`clckernel start\` | Setup | Scan codebase, propose governance plan, and materialize \`.clckernel.yaml\`. |
 
 ---
@@ -173,7 +177,12 @@ When given a command matching \`clckernel <action>\` or \`/clckernel <action>\`,
 ${this.getSafeguards().map(s => `- ${s}`).join('\n')}
 `;
 
-    fs.writeFileSync(path.join(targetDir, 'AGENTS.md'), dualLayerAgents, 'utf-8');
+    // Guard: never overwrite a project-customized AGENTS.md (e.g. a Laila MOS
+    // law file carrying domain invariants the template cannot know about).
+    const dualAgentsPath = path.join(targetDir, 'AGENTS.md');
+    if (!fs.existsSync(dualAgentsPath)) {
+      fs.writeFileSync(dualAgentsPath, dualLayerAgents, 'utf-8');
+    }
 
     // 3. Create AI IDE mirror symlinks
     const mirrors = ['CLAUDE.md', 'GEMINI.md', '.cursorrules', '.windsurfrules'];

package/src/adapters/base.js

@@ -57,6 +57,10 @@ class BaseAdapter {
   }
 
   provision(targetDir, config) {
+    // Subclasses that render their own AGENTS.md pass { skipAgentsMd: true }
+    // so this generic law file is never written alongside (or over) theirs.
+    const skipAgentsMd = !!(config && config.skipAgentsMd);
+
     // 1. Create docs/ and sdds/
     fs.mkdirSync(path.join(targetDir, 'docs', 'Journal'), { recursive: true });
     fs.mkdirSync(path.join(targetDir, 'docs', 'Architecture'), { recursive: true });
@@ -75,7 +79,7 @@ class BaseAdapter {
 
     // 3. Write AGENTS.md
     const isFront = this.projectType === 'frontend';
-    const agentsContent = `# 🔨 CLC Kernel ${this.name} (${this.projectType.toUpperCase()}) — AGENTS
+    const agentsContent = skipAgentsMd ? '' : `# 🔨 CLC Kernel ${this.name} (${this.projectType.toUpperCase()}) — AGENTS
 
 This document is the **authoritative law** for AI agents working in this repository.
 Forged by **CLC Kernel: The AI Agent Governance Engine**.
@@ -102,7 +106,14 @@ Forged by **CLC Kernel: The AI Agent Governance Engine**.
 ## 2. Core AI Safeguards (${this.name})
 ${this.getSafeguards().map(s => `- ${s}`).join('\n')}
 `;
-    fs.writeFileSync(path.join(targetDir, 'AGENTS.md'), agentsContent, 'utf-8');
+    // Guard: never overwrite a project-customized AGENTS.md.
+    if (skipAgentsMd) {
+      return;
+    }
+    const agentsPath = path.join(targetDir, 'AGENTS.md');
+    if (!fs.existsSync(agentsPath)) {
+      fs.writeFileSync(agentsPath, agentsContent, 'utf-8');
+    }
   }
 }
 

package/src/generator.js

@@ -338,9 +338,16 @@ When given a command matching \`clckernel <action>\` or \`/clckernel <action>\`,
 | \`clckernel doctor\` | Diagnostics | Check git pre-commit hooks, IDE symlinks, and AST engine integrity. |
 | \`clckernel commit <message>\` | Version Control | Run full audit, verify tests pass, ensure no changes outside SDD scope, and commit with conventional commits (never add AI attribution). |
 | \`clckernel guard create <name>\` | Safeguards | Scaffold a new AST guard in the stack's native language in \`tools/guards/\`. |
+| \`clckernel update\` | Maintenance | Non-destructive update: refresh core tools, playbooks & symlinks (preserves SDDs & custom guards). |
 | \`clckernel start\` | Setup | Scan codebase, propose governance plan, and materialize \`.clckernel.yaml\`. |
 `;
-    fs.writeFileSync(path.join(targetDir, 'AGENTS.md'), agentsContent, 'utf-8');
+    // Guard: never overwrite an existing project-customized AGENTS.md.
+    // This prevents clckernel update from replacing Laila MOS invariants
+    // (carousel format, one-question-onboarding, dynamic calendar, immutability).
+    if (!fs.existsSync(path.join(targetDir, 'AGENTS.md'))) {
+      fs.writeFileSync(path.join(targetDir, 'AGENTS.md'), agentsContent, 'utf-8');
+    }
+
   }
 
   // Step 2: Install tools (manifest-driven or fallback)

package/src/index.js

@@ -14,16 +14,23 @@ async function runCli() {
   const command = args[0];
 
   let targetDir = process.cwd();
-  if (command && !command.startsWith('-') && command !== 'doctor') {
+  if (command && !command.startsWith('-') && command !== 'doctor' && command !== 'update') {
     targetDir = path.resolve(command);
   }
 
   if (command === 'doctor' || args.includes('--doctor')) {
-    if (args[1]) targetDir = path.resolve(args[1]);
+    if (args[1] && args[1] !== '--doctor') targetDir = path.resolve(args[1]);
     runDoctor(targetDir);
     return;
   }
 
+  if (command === 'update' || args.includes('--update')) {
+    if (args[1] && args[1] !== '--update') targetDir = path.resolve(args[1]);
+    const { runUpdate } = require('./updater');
+    await runUpdate(targetDir);
+    return;
+  }
+
   // 1. Print Pro ASCII Banner
   printBanner();
 

package/src/updater.js

@@ -0,0 +1,95 @@
+/**
+ * CLC Kernel — Non-Destructive Harness Updater
+ * Safely updates core AST tools, skills, playbooks, and IDE symlinks in an existing
+ * project while guaranteeing 100% preservation of:
+ * - Local specifications (sdds/)
+ * - Custom AST guards (tools/guards/)
+ * - Project configuration and custom thresholds (.clckernel.yaml / .clc-forge.yaml)
+ * - Application source code and domain models
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { autoDetectStack } = require('./detector');
+const { generateHarness } = require('./generator');
+
+function updateHarness(targetDir = process.cwd(), options = {}) {
+  const resolvedDir = path.resolve(targetDir);
+
+  if (!fs.existsSync(resolvedDir)) {
+    throw new Error(`Target directory "${resolvedDir}" does not exist.`);
+  }
+
+  // 1. Detect Stack
+  const detected = autoDetectStack(resolvedDir);
+
+  // 2. Identify existing preserved assets
+  const preserved = {
+    sdds: fs.existsSync(path.join(resolvedDir, 'sdds')),
+    customGuards: fs.existsSync(path.join(resolvedDir, 'tools', 'guards')),
+    configYaml: fs.existsSync(path.join(resolvedDir, '.clckernel.yaml')) || fs.existsSync(path.join(resolvedDir, '.clc-forge.yaml')),
+  };
+
+  // 3. Run harness generation (refreshes tools, hooks, skills, and symlinks)
+  generateHarness(resolvedDir, detected);
+
+  // 4. Ensure AGENTS.md documents the update command in its command table.
+  // Non-destructive: only inject into a file that already carries the CLC
+  // Kernel command table, and only when the row is missing (idempotent).
+  // A project-customized AGENTS.md without that structure is left untouched.
+  const agentsPath = path.join(resolvedDir, 'AGENTS.md');
+  if (fs.existsSync(agentsPath)) {
+    let agentsContent = fs.readFileSync(agentsPath, 'utf-8');
+    if (!agentsContent.includes('clckernel update')) {
+      if (agentsContent.includes('| `clckernel start`')) {
+        agentsContent = agentsContent.replace(
+          '| `clckernel start`',
+          '| `clckernel update` | Maintenance | Non-destructive update: refresh core tools, playbooks & symlinks (preserves SDDs & custom guards). |\n| `clckernel start`'
+        );
+        fs.writeFileSync(agentsPath, agentsContent, 'utf-8');
+      } else if (agentsContent.includes('## 3. Universal Command Interface')) {
+        agentsContent += '\n| `clckernel update` | Maintenance | Non-destructive update: refresh core tools, playbooks & symlinks (preserves SDDs & custom guards). |\n';
+        fs.writeFileSync(agentsPath, agentsContent, 'utf-8');
+      }
+    }
+  }
+
+  return {
+    success: true,
+    targetDir: resolvedDir,
+    preserved,
+    refreshed: {
+      tools: true,
+      skills: true,
+      symlinks: true,
+      hooks: true,
+    },
+  };
+}
+
+async function runUpdate(targetDir = process.cwd()) {
+  const { colors, printBanner } = require('./ui');
+  printBanner();
+
+  console.log(`\n${colors.cyan}🔄 Actualizando CLC Kernel en:${colors.reset} ${targetDir}\n`);
+
+  try {
+    const result = updateHarness(targetDir);
+
+    console.log(`${colors.green}✔ Salvaguardas estándar actualizadas en tools/${colors.reset}`);
+    console.log(`${colors.green}✔ Playbooks y Skills agénticos actualizados en .agents/skills/${colors.reset}`);
+    console.log(`${colors.green}✔ Enlaces simbióticos de IDEs actualizados (Cursor, Claude, Copilot, Antigravity)${colors.reset}`);
+    console.log(`${colors.green}✔ Hooks de git sincronizados${colors.reset}`);
+    console.log(`\n${colors.bold}🔒 ACTIVOS PRESERVADOS AL 100%:${colors.reset}`);
+    console.log(`   • ${colors.emerald}sdds/${colors.reset} (Especificaciones locales intactas)`);
+    console.log(`   • ${colors.emerald}tools/guards/${colors.reset} (Reglas y salvaguardas personalizadas intactas)`);
+    console.log(`   • ${colors.emerald}.clckernel.yaml${colors.reset} (Configuraciones de equipo intactas)\n`);
+    console.log(`${colors.green}✨ ¡Proyecto actualizado con éxito a la última versión de CLC Kernel!${colors.reset}\n`);
+    return result;
+  } catch (err) {
+    console.error(`\n❌ Error actualizando el arnés: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = { updateHarness, runUpdate };