clckernel 1.2.8 → 1.2.9

package/README.es.md

@@ -17,6 +17,18 @@ 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)
+- [⚡ Guía Paso a Paso (Ciclo Completo)](#-guía-paso-a-paso-ciclo-completo)
+- [🎮 Interfaz Universal de Comandos](#-interfaz-universal-de-comandos)
+- [🌐 Ecosistemas Soportados y Arquetipos](#-ecosistemas-soportados-y-arquetipos)
+- [🧩 Herramientas Complementarias (Opcionales)](#-herramientas-complementarias-opcionales)
+- [📄 Licencia](#-licencia)
+
+---
+
+<a id="casos-de-uso"></a>
 ## 🎯 Casos de Uso
 
 | Caso de Uso | Problema que Resuelve | Cómo lo Resuelve CLC Kernel |
@@ -28,6 +40,7 @@ Los agentes de programación con IA (Cursor, Claude Code, Windsurf, Copilot) cod
 
 ---
 
+<a id="aiup"></a>
 ## 🏛️ El Proceso Unificado de IA (AIUP)
 
 ```
@@ -48,6 +61,73 @@ Los agentes de programación con IA (Cursor, Claude Code, Windsurf, Copilot) cod
 
 ---
 
+<a id="guia-paso-a-paso"></a>
+## ⚡ Guía Paso a Paso (Ciclo Completo)
+
+```
+[1. Terminal]           [2. Chat del LLM]            [3. Bucle TDD]                [4. Git Commit]
+npx clckernel   ───►   clckernel start   ───►   "Feature X con harness"   ───►   Hooks Pre-commit
+(Bootstrap)            (Setup Interactivo)          (SDD -> HIT -> Tests)         (Guardián AST & Secretos)
+```
+
+### 1️⃣ Paso 1: Inicializar el Repositorio (Terminal)
+```bash
+npx clckernel start
+```
+Detecta el framework, genera `AGENTS.md`, crea symlinks dinámicos para todos los IDEs (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`), provisiona hooks pre-commit e instala verificadores AST en `tools/`.
+
+### 2️⃣ Paso 2: Inicializar en el Chat del IDE (CLI Conversacional)
+Abrí Cursor, Claude Code, Gemini CLI, Windsurf o Copilot y escribí:
+> `clckernel start`
+
+El agente escanea tu código en silencio, propone un plan de gobernanza adaptado a tu stack y genera `.clckernel.yaml`.
+
+### 3️⃣ Paso 3: Desarrollar con el Arnés AIUP
+Al solicitar una funcionalidad o corrección, indicá al agente:
+> *"Implementa el endpoint de autenticación. **Usa el harness de CLC Kernel**."*
+
+El agente ejecutará de forma autónoma el ciclo AIUP completo:
+1. **Investigación y Causa Raíz:** Inspecciona el código base y dependencias.
+2. **Especificación SDD Local:** Redacta contratos de API y planes de prueba en `sdds/{cambio}/spec.md`.
+3. **Revisión HIT:** Solicita tu revisión y aprobación de los contratos propuestos.
+4. **Fase Roja TDD:** Escribe un test de regresión que falle demostrando el requerimiento.
+5. **Implementación Verde:** Escribe el código mínimo necesario respetando el aislamiento de capas.
+6. **Compuerta de Auditoría AST:** Ejecuta `node tools/audit.js` y emite el resumen de verificación.
+
+### 4️⃣ Paso 4: Verificación Determinística de Guards (Git Commit)
+```bash
+git add .
+git commit -m "feat(auth): add user authentication endpoint"
+```
+Los hooks pre-commit ejecutan automáticamente los escáneres AST (Clean Architecture, Fuga de Secretos, Scope Guard, Idempotencia de Migraciones). Cualquier violación **bloquea físicamente** el commit.
+
+### 5️⃣ Paso 5: Auditar la Salud del Repositorio en Cualquier Momento (Doctor)
+```bash
+npx clckernel doctor
+```
+Audita el 100% de cumplimiento en `AGENTS.md`, `sdds/`, `tools/`, runners de pruebas activos y hooks de Git.
+
+---
+
+<a id="interfaz-universal-de-comandos"></a>
+## 🎮 Interfaz Universal de Comandos (Todos los LLMs y Agentes)
+
+CLC Kernel provee una gramática de comandos determinista soportada de forma nativa por **Claude Code, Cursor, Codeium/Windsurf, Copilot, Gemini y Antigravity**:
+
+| Comando | Categoría | Protocolo de Ejecución Obligatorio |
+|---|---|---|
+| `clckernel feature <nombre>` | Funcionalidad | Ciclo AIUP completo: Investigación -> Spec Local (`sdds/{nombre}/spec.md`) -> Revisión HIT -> Fase Roja TDD -> Implementación Verde -> Auditoría. |
+| `clckernel fix <descripción>` | Corrección | Análisis de causa raíz (sin editar código) -> Test de regresión que falle -> Corrección quirúrgica limpia -> Compuerta de auditoría. |
+| `clckernel test` | Verificación | Ejecuta la suite de pruebas en el runner nativo del stack y confirma estado verde limpio. |
+| `clckernel audit` | Verificación | Ejecuta `node tools/audit.js` o `python tools/audit.py` y emite el Resumen Educativo. |
+| `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 start` | Configuración | Detecta el stack automáticamente, propone el ciclo de vida AIUP y genera `.clckernel.yaml`. |
+
+---
+
+<a id="ecosistemas-soportados"></a>
 ## 🌐 Ecosistemas Soportados y Arquetipos
 
 | Ecosistema | Firma de Detección | Test Runner | Salvaguardas Nativas |
@@ -64,28 +144,7 @@ Los agentes de programación con IA (Cursor, Claude Code, Windsurf, Copilot) cod
 
 ---
 
-## 🚀 Inicio Rápido
-
-### 1. Inicializar en Terminal
-```bash
-npx clckernel start
-```
-Detecta el framework, genera `AGENTS.md`, crea symlinks para todos los IDEs, provisiona hooks pre-commit e instala verificadores AST en `tools/`.
-
-### 2. Verificar Estado de Salud
-```bash
-npx clckernel doctor
-```
-Audita hooks de Git, test runners activos y la integridad del motor AST.
-
-### 3. Desarrollar con Gobernanza
-En el chat del IDE (Cursor, Claude Code, Gemini CLI, Windsurf):
-> *"Implementa el endpoint de autenticación. **Usa el harness de CLC Kernel**."*
-
-El agente ejecutará el ciclo AIUP completo: **Especificación SDD -> Aprobación HIT -> Test Rojo -> Implementación Verde -> Auditoría AST**.
-
----
-
+<a id="herramientas-complementarias"></a>
 ## 🧩 Herramientas Complementarias (Opcionales)
 
 CLC Kernel se enfoca estrictamente en gobernanza y opera con **cero dependencias foráneas**. Se integra de forma modular con:
@@ -95,5 +154,6 @@ CLC Kernel se enfoca estrictamente en gobernanza y opera con **cero dependencias
 
 ---
 
+<a id="licencia"></a>
 ## 📄 Licencia
 MIT © [CarlosLeonCode](https://github.com/carlosleoncode)

package/README.md

@@ -17,6 +17,18 @@ 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)
+- [⚡ Step-by-Step Guide (Full Lifecycle)](#-step-by-step-guide-full-lifecycle)
+- [🎮 Universal Command Interface](#-universal-command-interface)
+- [🌐 Supported Stacks & Archetypes](#-supported-stacks--archetypes)
+- [🧩 Optional Ecosystem Companions](#-optional-ecosystem-companions)
+- [📄 License](#-license)
+
+---
+
+<a id="use-cases"></a>
 ## 🎯 Use Cases
 
 | Use Case | Problem It Solves | How CLC Kernel Solves It |
@@ -28,6 +40,7 @@ AI coding agents (Cursor, Claude Code, Windsurf, Copilot) code fast, but without
 
 ---
 
+<a id="aiup"></a>
 ## 🏛️ The AI Unified Process (AIUP)
 
 ```
@@ -48,6 +61,73 @@ AI coding agents (Cursor, Claude Code, Windsurf, Copilot) code fast, but without
 
 ---
 
+<a id="step-by-step-guide"></a>
+## ⚡ Step-by-Step Guide (Full Lifecycle)
+
+```
+[1. Terminal]           [2. AI Chat]                 [3. TDD Loop]                 [4. Git Commit]
+npx clckernel   ───►   clckernel start   ───►   "Feature X with harness"   ───►   Pre-commit Hooks
+(Bootstrap)            (Interactive Setup)          (SDD -> HIT -> Tests)         (AST & Secret Guard)
+```
+
+### 1️⃣ Step 1: Bootstrap the Repository (Terminal)
+```bash
+npx clckernel start
+```
+Auto-detects your framework, generates `AGENTS.md`, creates dynamic IDE symlinks (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`), provisions pre-commit hooks, and creates native AST checks in `tools/`.
+
+### 2️⃣ Step 2: Initialize in Your AI Chat (Conversational CLI)
+Open Cursor, Claude Code, Gemini CLI, Windsurf, or Copilot and type:
+> `clckernel start`
+
+The agent scans your codebase silently, proposes an AIUP governance plan tailored to your framework, and generates `.clckernel.yaml`.
+
+### 3️⃣ Step 3: Develop with the AIUP Harness
+When requesting features or bugfixes, instruct your agent:
+> *"Add user authentication endpoint. **Follow the CLC Kernel harness**."*
+
+The agent autonomously executes the complete AIUP cycle:
+1. **Research & Root Cause Analysis:** Inspects codebase and dependencies.
+2. **Local SDD Spec:** Writes API contracts and test plans in `sdds/{change}/spec.md`.
+3. **HIT Review:** Requests your review and approval on proposed contracts.
+4. **TDD Red Phase:** Writes a failing regression test proving the requirement.
+5. **Clean Implementation (Green Phase):** Writes minimal code to pass tests while respecting layer isolation.
+6. **AST Audit Gate:** Runs `node tools/audit.js` and outputs the verification summary.
+
+### 4️⃣ Step 4: Deterministic Guard Verification (Git Commit)
+```bash
+git add .
+git commit -m "feat(auth): add user authentication endpoint"
+```
+Pre-commit hooks automatically execute AST scanners (Clean Architecture, Secret Leaks, Scope Guard, Migration Idempotency). Any non-compliant commit is **physically blocked** before touching Git history.
+
+### 5️⃣ Step 5: Verify Repository Health Anytime (Doctor)
+```bash
+npx clckernel doctor
+```
+Audits 100% compliance across `AGENTS.md`, `sdds/`, `tools/`, active test runners, and Git hooks.
+
+---
+
+<a id="universal-command-interface"></a>
+## 🎮 Universal Command Interface (All LLMs & Agents)
+
+CLC Kernel provides a deterministic command grammar supported natively by **Claude Code, Cursor, Codeium/Windsurf, Copilot, Gemini, and Antigravity**:
+
+| Command | Category | Mandatory Execution Protocol |
+|---|---|---|
+| `clckernel feature <name>` | Feature | Full AIUP cycle: Research -> Local Spec (`sdds/{name}/spec.md`) -> HIT review -> TDD Red Phase -> Green Implementation -> Audit. |
+| `clckernel fix <issue>` | Bug Fix | Root-cause analysis (no direct code edits) -> Failing regression test -> Surgical clean fix -> Audit gate. |
+| `clckernel test` | Verification | Runs repository test suite in the native stack runner and confirms clean pass. |
+| `clckernel audit` | Verification | Runs `node tools/audit.js` or `python tools/audit.py` and emits the Educational Summary. |
+| `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 start` | Setup | Auto-detects stack, proposes AIUP lifecycle, and generates `.clckernel.yaml`. |
+
+---
+
+<a id="supported-stacks"></a>
 ## 🌐 Supported Stacks & Archetypes
 
 | Ecosystem | Detection Signature | Test Runner | Native Safeguards |
@@ -64,28 +144,7 @@ AI coding agents (Cursor, Claude Code, Windsurf, Copilot) code fast, but without
 
 ---
 
-## 🚀 Quickstart
-
-### 1. Initialize in Terminal
-```bash
-npx clckernel start
-```
-Auto-detects your framework, generates `AGENTS.md`, creates IDE rule symlinks, provisions pre-commit hooks, and creates native AST checks in `tools/`.
-
-### 2. Verify Health
-```bash
-npx clckernel doctor
-```
-Audits Git hooks, active test runners, and AST engine integrity.
-
-### 3. Develop with Agentic Governance
-In your IDE chat (Cursor, Claude Code, Gemini CLI, Windsurf):
-> *"Implement authentication endpoint. **Follow the CLC Kernel harness**."*
-
-The agent executes the full AIUP loop: **SDD Spec -> HIT Review -> Failing Test (Red) -> Implementation (Green) -> AST Audit**.
-
----
-
+<a id="ecosystem-companions"></a>
 ## 🧩 Optional Ecosystem Companions
 
 CLC Kernel focuses strictly on governance and runs with **zero foreign dependencies**. It seamlessly integrates with companion tools:
@@ -95,5 +154,6 @@ CLC Kernel focuses strictly on governance and runs with **zero foreign dependenc
 
 ---
 
+<a id="license"></a>
 ## 📄 License
 MIT © [CarlosLeonCode](https://github.com/carlosleoncode)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clckernel",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "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

@@ -95,6 +95,13 @@ class AgentOSAdapter extends BaseAdapter {
         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',
+        command: 'node tools/check_test_calendar_sync.js',
+        description: 'Test calendar harness synchronization and parity check'
+      },
       {
         name: 'scan_secrets',
         language: 'node',
@@ -146,6 +153,22 @@ When operating as domain agents for end-users and non-technical operators:
 
 ---
 
+## 🎮 Universal Command Interface (All LLMs & Agents)
+When given a command matching \`clckernel <action>\` or \`/clckernel <action>\`, execute the deterministic state machine below:
+
+| Command | Lifecycle Phase | Mandatory Execution Protocol |
+|---|---|---|
+| \`clckernel feature <name>\` | New Feature | 1. Research affected layers.<br>2. Author local spec in \`sdds/{name}/spec.md\`.<br>3. Present HIT review to user and wait for approval.<br>4. Write failing test (Red Phase).<br>5. Implement clean code (Green Phase).<br>6. Run \`node tools/audit.js\` (or \`audit.py\`). |
+| \`clckernel fix <issue>\` | Bug Fix | 1. Investigate root cause (no code edits).<br>2. Reproduce with failing test (Red Phase).<br>3. Minimal surgical fix respecting Clean Arch (Green Phase).<br>4. Run audit gate without skipping. |
+| \`clckernel test\` | Verification | Run test suite and verify clean pass (exit code 0). |
+| \`clckernel audit\` | Verification | Run \`node tools/audit.js\` or \`python tools/audit.py\` and output the Educational Summary. |
+| \`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 start\` | Setup | Scan codebase, propose governance plan, and materialize \`.clckernel.yaml\`. |
+
+---
+
 ## 🛡️ Core AI Safeguards
 ${this.getSafeguards().map(s => `- ${s}`).join('\n')}
 `;

package/src/generator.js

@@ -325,6 +325,20 @@ ${isFront ? `- UI Component Reuse First (components/ui/ & semantic tokens)
 - Database Efficiency & N+1 Performance Guard
 - Database Migration Idempotency Guard
 - Memory Guard (Engram / Graphify)`}
+
+## 3. Universal Command Interface (All LLMs & Agents)
+When given a command matching \`clckernel <action>\` or \`/clckernel <action>\`, execute the deterministic state machine below:
+
+| Command | Lifecycle Phase | Mandatory Execution Protocol |
+|---|---|---|
+| \`clckernel feature <name>\` | New Feature | 1. Research affected layers.<br>2. Author local spec in \`sdds/{name}/spec.md\`.<br>3. Present HIT review to user and wait for approval.<br>4. Write failing test (Red Phase).<br>5. Implement clean code (Green Phase).<br>6. Run \`node tools/audit.js\` (or \`audit.py\`). |
+| \`clckernel fix <issue>\` | Bug Fix | 1. Investigate root cause (no code edits).<br>2. Reproduce with failing test (Red Phase).<br>3. Minimal surgical fix respecting Clean Arch (Green Phase).<br>4. Run audit gate without skipping. |
+| \`clckernel test\` | Verification | Run test suite (\`${config.testRunner || 'npm test'}\`) and verify clean pass (exit code 0). |
+| \`clckernel audit\` | Verification | Run \`node tools/audit.js\` or \`python tools/audit.py\` and output the Educational Summary. |
+| \`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 start\` | Setup | Scan codebase, propose governance plan, and materialize \`.clckernel.yaml\`. |
 `;
     fs.writeFileSync(path.join(targetDir, 'AGENTS.md'), agentsContent, 'utf-8');
   }
@@ -372,68 +386,31 @@ function installAgenticCLI(targetDir) {
   // 1. Crear el Directorio de Skills
   const skillDir = path.join(targetDir, '.agents', 'skills', 'clckernel_cli');
   const legacySkillDir = path.join(targetDir, '.agents', 'skills', 'clc_forge_cli');
-  fs.mkdirSync(skillDir, { recursive: true });
-  fs.mkdirSync(legacySkillDir, { recursive: true });
-
-  // 2. Inyectar el SKILL.md Maestro
-  const skillContent = `---
-name: clckernel_cli
-description: Conversational CLI Orchestrator for the CLC Kernel AI Agent Governance Engine.
-triggers:
-  - clckernel start
-  - clckernel create_guard
-  - clckernel remove_guard
-  - clckernel add_phase
-  - clckernel remove_phase
-  - clc_forge start
-  - clc_forge create_guard
----
-
-# 🤖 CLC Kernel — Conversational CLI
-
-You are the internal runtime engine of CLC Kernel (AIUP Orchestrator). 
-DO NOT suggest terminal bash commands for these triggers; YOU are the execution environment. Your job is to guide the user through the agent governance lifecycle via chat, dynamically discovering the environment, and manipulating configuration files.
-
-## 🚀 INTENT: \`clckernel start\` (or \`clc_forge start\`)
-Execute this exact sequence without skipping steps:
-
-### Phase 1: Silent Discovery
-Scan the current project using your file-reading capabilities. Identify the primary tech stack by looking for signature files (e.g., \`package.json\`, \`Gemfile\`, \`Cargo.toml\`, \`go.mod\`). 
-*Golden Rule: Do not assume the language. Read the files to establish context.*
-
-### Phase 2: Interview & Proposal
-Introduce yourself as CLC Kernel and state the detected stack.
-Propose a standard governance plan for that ecosystem (SDD + TDD + stack-specific Safeguards).
-ASK the user directly: 
-1. "Should we activate these standard phases, or do you want to define custom ones?"
-2. "Do you have any specific security needs that require a custom Guard?"
-**STOP.** Wait for the user's response.
-
-### Phase 3: Materialization
-Based on user approval, generate and write the \`.clckernel.yaml\` file in the project root.
-
----
-
-## 🛠️ INTENT: \`clckernel create_guard\`
-1. Ask the user what behavior they want to audit or block. **STOP.** Wait for technical details.
-2. Based on the detected stack, write the linter/guard script in the **NATIVE ECOSYSTEM LANGUAGE** (Ruby for Rails, Go \`ast\` for Golang, Python \`ast\` for FastAPI, JS for Node). Save it in \`tools/guards/\`.
-3. Update the \`.clckernel.yaml\` file to include the new Guard.
-
----
-
-## 🗑️ INTENT: \`clckernel remove_guard\`
-1. Ask which guard to remove and if the script should be deleted. **STOP.** Wait for response.
-2. Update \`.clckernel.yaml\` and delete the script from \`tools/guards/\` if requested.
-
----
-
-## 🔄 INTENT: \`clckernel add_phase\` / \`clckernel remove_phase\`
-1. Ask for details of the lifecycle phase to add or remove. **STOP.** Wait for response.
-2. Update the \`execution_phases\` block in \`.clckernel.yaml\`, preserving the logical sequence.
-`;
-  
-  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skillContent, 'utf-8');
-  fs.writeFileSync(path.join(legacySkillDir, 'SKILL.md'), skillContent, 'utf-8');
+  const skillRefDir = path.join(skillDir, 'reference');
+  const legacySkillRefDir = path.join(legacySkillDir, 'reference');
+  fs.mkdirSync(skillRefDir, { recursive: true });
+  fs.mkdirSync(legacySkillRefDir, { recursive: true });
+
+  // 2. Inyectar el SKILL.md Maestro y Playbooks de Referencia
+  const bundledSkillDir = path.join(__dirname, '..', '.agents', 'skills', 'clckernel_cli');
+  const bundledSkillFile = path.join(bundledSkillDir, 'SKILL.md');
+  const bundledRefDir = path.join(bundledSkillDir, 'reference');
+
+  if (fs.existsSync(bundledSkillFile)) {
+    fs.copyFileSync(bundledSkillFile, path.join(skillDir, 'SKILL.md'));
+    fs.copyFileSync(bundledSkillFile, path.join(legacySkillDir, 'SKILL.md'));
+  }
+
+  if (fs.existsSync(bundledRefDir)) {
+    const playbooks = fs.readdirSync(bundledRefDir);
+    for (const pb of playbooks) {
+      const srcPb = path.join(bundledRefDir, pb);
+      if (fs.statSync(srcPb).isFile()) {
+        fs.copyFileSync(srcPb, path.join(skillRefDir, pb));
+        fs.copyFileSync(srcPb, path.join(legacySkillRefDir, pb));
+      }
+    }
+  }
 
   // 3. Crear Symlinks Dinámicos al AGENTS.md (El Single Source of Truth)
   const sourceFile = 'AGENTS.md';

package/tools/check_test_calendar_sync.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Test Calendar Parity & Auto-Sync Guard
+ * Ensures that any modification made to the calendar engine (templates/content-calendar/)
+ * is immediately synchronized to the test calendar harness (tests/).
+ * Self-contained: uses only Node.js built-ins.
+ *
+ * @param {string} targetDir - Directory to scan (defaults to cwd)
+ * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
+ */
+const check = async function checkTestCalendarSync(targetDir) {
+  const fs = require('fs');
+  const path = require('path');
+
+  const dir = targetDir || process.cwd();
+  const templateDir = path.join(dir, 'templates', 'content-calendar');
+  const testDir = path.join(dir, 'tests');
+
+  if (!fs.existsSync(templateDir) || !fs.existsSync(testDir)) {
+    return {
+      exitCode: 0,
+      skipped: true,
+      name: 'check_test_calendar_sync',
+      data: { violations: [], message: 'No templates/content-calendar or tests/ directory found' }
+    };
+  }
+
+  const syncPairs = [
+    { src: path.join(templateDir, 'index.html'), dest: path.join(testDir, 'index.html'), label: 'index.html' },
+    { src: path.join(templateDir, 'data.js'), dest: path.join(testDir, 'data.js'), label: 'data.js' },
+    { src: path.join(templateDir, 'data.js'), dest: path.join(testDir, 'mock-data.js'), label: 'mock-data.js' }
+  ];
+
+  const syncedFiles = [];
+  const violations = [];
+
+  for (const pair of syncPairs) {
+    if (!fs.existsSync(pair.src)) continue;
+
+    let needsSync = false;
+    if (!fs.existsSync(pair.dest)) {
+      needsSync = true;
+    } else {
+      const srcBuf = fs.readFileSync(pair.src);
+      const destBuf = fs.readFileSync(pair.dest);
+      if (!srcBuf.equals(destBuf)) {
+        needsSync = true;
+      }
+    }
+
+    if (needsSync) {
+      try {
+        fs.copyFileSync(pair.src, pair.dest);
+        syncedFiles.push(pair.label);
+      } catch (err) {
+        violations.push({
+          file: pair.label,
+          message: `Failed to synchronize ${pair.label}: ${err.message}`
+        });
+      }
+    }
+  }
+
+  // Also verify mock-content.json has channelProfiles if data.js has it
+  const dataJsPath = path.join(templateDir, 'data.js');
+  const mockContentPath = path.join(testDir, 'mock-content.json');
+  if (fs.existsSync(dataJsPath) && fs.existsSync(mockContentPath)) {
+    try {
+      const dataJsContent = fs.readFileSync(dataJsPath, 'utf-8');
+      if (dataJsContent.includes('"channelProfiles"') && !fs.readFileSync(mockContentPath, 'utf-8').includes('"channelProfiles"')) {
+        // Hydrate channelProfiles from data.js
+        const match = dataJsContent.match(/"channelProfiles":\s*\{[\s\S]*?\n\s{4}\}/);
+        if (match) {
+          let mockJson = fs.readFileSync(mockContentPath, 'utf-8');
+          mockJson = mockJson.replace(/"pillarMix":\s*\{[\s\S]*?\n\s{4}\}/, (m) => `${m},\n    ${match[0]}`);
+          fs.writeFileSync(mockContentPath, mockJson, 'utf-8');
+          syncedFiles.push('mock-content.json');
+        }
+      }
+    } catch (e) {
+      // non-fatal
+    }
+  }
+
+  const exitCode = violations.length > 0 ? 1 : 0;
+  const message = violations.length > 0
+    ? `Failed to sync ${violations.length} test calendar files`
+    : (syncedFiles.length > 0
+        ? `Auto-synchronized ${syncedFiles.length} test calendar file(s): ${syncedFiles.join(', ')}`
+        : 'Test calendar is 100% in sync with templates/content-calendar');
+
+  return {
+    exitCode,
+    skipped: false,
+    name: 'check_test_calendar_sync',
+    data: {
+      violations,
+      syncedFiles,
+      message
+    }
+  };
+};
+
+module.exports = check;
+
+if (require.main === module) {
+  check(process.argv[2]).then(result => {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.exitCode);
+  });
+}