@saulwade/swl-ses 2.6.0 → 2.8.0

package/hooks/lib/provenance-tracker.js

@@ -1,191 +1,191 @@
-'use strict';
-
-/**
- * Provenance Tracker — Rastreo de proveniencia de skills y componentes.
- *
- * Registra de dónde viene cada skill/agente instalado: si es del core SWL,
- * de un repo externo, de auto-evolución, o de la comunidad. Genera y lee
- * archivos meta.json por componente.
- *
- * Patrón adoptado de skillshare (internal/install/meta.go).
- *
- * Zero dependencias externas.
- *
- * Uso:
- *   const { registrarProveniencia, leerProveniencia, listarProveniencias } = require('./lib/provenance-tracker');
- *
- *   registrarProveniencia('/ruta/skill', {
- *     origin: 'core',
- *     repoUrl: 'https://github.com/saulwadeleon/swl-ses',
- *     version: '5.6.3',
- *   });
- *
- *   const meta = leerProveniencia('/ruta/skill');
- *   // { origin: 'core', repoUrl: '...', version: '5.6.3', installedAt: '...' }
- *
- * @module hooks/lib/provenance-tracker
- */
-
-const fs   = require('fs');
-const path = require('path');
-
-// Escritura atómica obligatoria para meta.json (regla CLAUDE.md).
-let atomicWriteJSON;
-try {
-  ({ atomicWriteJSON } = require('./atomic-write'));
-} catch {
-  atomicWriteJSON = (p, o) => fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8');
-}
-
-// ---------------------------------------------------------------------------
-// Constantes
-// ---------------------------------------------------------------------------
-
-const META_FILENAME = 'meta.json';
-
-/**
- * Orígenes válidos de un componente.
- * @readonly
- */
-const ORIGENES = Object.freeze({
-  CORE:           'core',           // Del paquete swl-ses
-  AUTO_EVOLUTION: 'auto-evolution', // Generado por /swl:evolucionar
-  IMPORTED:       'imported',       // Importado de repo externo
-  COMMUNITY:      'community',     // De skills.sh o similares
-  USERLAND:       'userland',       // Del usuario (_userland/)
-  ANTHROPIC:      'anthropic',      // De anthropics/skills
-});
-
-// ---------------------------------------------------------------------------
-// API pública
-// ---------------------------------------------------------------------------
-
-/**
- * Registra la proveniencia de un componente instalado.
- *
- * Crea o actualiza meta.json en el directorio del componente.
- *
- * @param {string} componentDir - Ruta al directorio del componente
- * @param {object} datos
- * @param {string} datos.origin     - Origen (ver ORIGENES)
- * @param {string} [datos.repoUrl]  - URL del repo de origen
- * @param {string} [datos.commit]   - Commit hash del origen
- * @param {string} [datos.version]  - Versión del sistema al instalar
- * @param {string} [datos.author]   - Autor o equipo
- * @param {string} [datos.note]     - Nota libre
- */
-function registrarProveniencia(componentDir, datos) {
-  const metaPath = path.join(componentDir, META_FILENAME);
-
-  const meta = {
-    origin: datos.origin || ORIGENES.CORE,
-    repoUrl: datos.repoUrl || null,
-    commit: datos.commit || null,
-    version: datos.version || null,
-    author: datos.author || null,
-    note: datos.note || null,
-    installedAt: new Date().toISOString(),
-    installedBy: `swl-ses v${datos.version || 'unknown'}`,
-  };
-
-  // Si ya existe, preservar datos anteriores y agregar historial
-  if (fs.existsSync(metaPath)) {
-    try {
-      const existing = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
-      // Mover datos anteriores a historial
-      if (!existing.history) existing.history = [];
-      const { history, ...prevData } = existing;
-      existing.history.push({ ...prevData, replacedAt: meta.installedAt });
-
-      // Actualizar con nuevos datos
-      Object.assign(existing, meta);
-      existing.history = existing.history.slice(-5); // Máximo 5 entradas de historial
-
-      atomicWriteJSON(metaPath, existing);
-    } catch {
-      // Error leyendo existente — sobrescribir
-      atomicWriteJSON(metaPath, meta);
-    }
-  } else {
-    atomicWriteJSON(metaPath, meta);
-  }
-}
-
-/**
- * Lee la proveniencia de un componente.
- *
- * @param {string} componentDir - Ruta al directorio del componente
- * @returns {object|null} Datos de proveniencia o null si no existe
- */
-function leerProveniencia(componentDir) {
-  const metaPath = path.join(componentDir, META_FILENAME);
-  if (!fs.existsSync(metaPath)) return null;
-
-  try {
-    return JSON.parse(fs.readFileSync(metaPath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Lista la proveniencia de todos los componentes en un directorio.
- *
- * @param {string} parentDir - Directorio padre (ej: habilidades/)
- * @returns {Array<{ name: string, origin: string, version: string, installedAt: string }>}
- */
-function listarProveniencias(parentDir) {
-  if (!fs.existsSync(parentDir)) return [];
-
-  const resultado = [];
-  const entries = fs.readdirSync(parentDir, { withFileTypes: true });
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const meta = leerProveniencia(path.join(parentDir, entry.name));
-    resultado.push({
-      name: entry.name,
-      origin: meta ? meta.origin : 'unknown',
-      version: meta ? meta.version : null,
-      installedAt: meta ? meta.installedAt : null,
-      repoUrl: meta ? meta.repoUrl : null,
-    });
-  }
-
-  return resultado;
-}
-
-/**
- * Genera un resumen de proveniencia por origen.
- *
- * @param {string} parentDir - Directorio padre
- * @returns {{ total: number, byOrigin: Object<string, number>, unknown: number }}
- */
-function resumenProveniencia(parentDir) {
-  const lista = listarProveniencias(parentDir);
-  const byOrigin = {};
-  let unknown = 0;
-
-  for (const item of lista) {
-    if (item.origin === 'unknown') {
-      unknown++;
-    } else {
-      byOrigin[item.origin] = (byOrigin[item.origin] || 0) + 1;
-    }
-  }
-
-  return { total: lista.length, byOrigin, unknown };
-}
-
-// ---------------------------------------------------------------------------
-// Exports
-// ---------------------------------------------------------------------------
-
-module.exports = {
-  registrarProveniencia,
-  leerProveniencia,
-  listarProveniencias,
-  resumenProveniencia,
-  ORIGENES,
-  META_FILENAME,
-};
+'use strict';
+
+/**
+ * Provenance Tracker — Rastreo de proveniencia de skills y componentes.
+ *
+ * Registra de dónde viene cada skill/agente instalado: si es del core SWL,
+ * de un repo externo, de auto-evolución, o de la comunidad. Genera y lee
+ * archivos meta.json por componente.
+ *
+ * Patrón adoptado de skillshare (internal/install/meta.go).
+ *
+ * Zero dependencias externas.
+ *
+ * Uso:
+ *   const { registrarProveniencia, leerProveniencia, listarProveniencias } = require('./lib/provenance-tracker');
+ *
+ *   registrarProveniencia('/ruta/skill', {
+ *     origin: 'core',
+ *     repoUrl: 'https://github.com/saulwadeleon/swl-ses',
+ *     version: '5.6.3',
+ *   });
+ *
+ *   const meta = leerProveniencia('/ruta/skill');
+ *   // { origin: 'core', repoUrl: '...', version: '5.6.3', installedAt: '...' }
+ *
+ * @module hooks/lib/provenance-tracker
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// Escritura atómica obligatoria para meta.json (regla CLAUDE.md).
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require('./atomic-write'));
+} catch {
+  atomicWriteJSON = (p, o) => fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+const META_FILENAME = 'meta.json';
+
+/**
+ * Orígenes válidos de un componente.
+ * @readonly
+ */
+const ORIGENES = Object.freeze({
+  CORE:           'core',           // Del paquete swl-ses
+  AUTO_EVOLUTION: 'auto-evolution', // Generado por /swl:evolucionar
+  IMPORTED:       'imported',       // Importado de repo externo
+  COMMUNITY:      'community',     // De skills.sh o similares
+  USERLAND:       'userland',       // Del usuario (_userland/)
+  ANTHROPIC:      'anthropic',      // De anthropics/skills
+});
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Registra la proveniencia de un componente instalado.
+ *
+ * Crea o actualiza meta.json en el directorio del componente.
+ *
+ * @param {string} componentDir - Ruta al directorio del componente
+ * @param {object} datos
+ * @param {string} datos.origin     - Origen (ver ORIGENES)
+ * @param {string} [datos.repoUrl]  - URL del repo de origen
+ * @param {string} [datos.commit]   - Commit hash del origen
+ * @param {string} [datos.version]  - Versión del sistema al instalar
+ * @param {string} [datos.author]   - Autor o equipo
+ * @param {string} [datos.note]     - Nota libre
+ */
+function registrarProveniencia(componentDir, datos) {
+  const metaPath = path.join(componentDir, META_FILENAME);
+
+  const meta = {
+    origin: datos.origin || ORIGENES.CORE,
+    repoUrl: datos.repoUrl || null,
+    commit: datos.commit || null,
+    version: datos.version || null,
+    author: datos.author || null,
+    note: datos.note || null,
+    installedAt: new Date().toISOString(),
+    installedBy: `swl-ses v${datos.version || 'unknown'}`,
+  };
+
+  // Si ya existe, preservar datos anteriores y agregar historial
+  if (fs.existsSync(metaPath)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+      // Mover datos anteriores a historial
+      if (!existing.history) existing.history = [];
+      const { history, ...prevData } = existing;
+      existing.history.push({ ...prevData, replacedAt: meta.installedAt });
+
+      // Actualizar con nuevos datos
+      Object.assign(existing, meta);
+      existing.history = existing.history.slice(-5); // Máximo 5 entradas de historial
+
+      atomicWriteJSON(metaPath, existing);
+    } catch {
+      // Error leyendo existente — sobrescribir
+      atomicWriteJSON(metaPath, meta);
+    }
+  } else {
+    atomicWriteJSON(metaPath, meta);
+  }
+}
+
+/**
+ * Lee la proveniencia de un componente.
+ *
+ * @param {string} componentDir - Ruta al directorio del componente
+ * @returns {object|null} Datos de proveniencia o null si no existe
+ */
+function leerProveniencia(componentDir) {
+  const metaPath = path.join(componentDir, META_FILENAME);
+  if (!fs.existsSync(metaPath)) return null;
+
+  try {
+    return JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lista la proveniencia de todos los componentes en un directorio.
+ *
+ * @param {string} parentDir - Directorio padre (ej: habilidades/)
+ * @returns {Array<{ name: string, origin: string, version: string, installedAt: string }>}
+ */
+function listarProveniencias(parentDir) {
+  if (!fs.existsSync(parentDir)) return [];
+
+  const resultado = [];
+  const entries = fs.readdirSync(parentDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const meta = leerProveniencia(path.join(parentDir, entry.name));
+    resultado.push({
+      name: entry.name,
+      origin: meta ? meta.origin : 'unknown',
+      version: meta ? meta.version : null,
+      installedAt: meta ? meta.installedAt : null,
+      repoUrl: meta ? meta.repoUrl : null,
+    });
+  }
+
+  return resultado;
+}
+
+/**
+ * Genera un resumen de proveniencia por origen.
+ *
+ * @param {string} parentDir - Directorio padre
+ * @returns {{ total: number, byOrigin: Object<string, number>, unknown: number }}
+ */
+function resumenProveniencia(parentDir) {
+  const lista = listarProveniencias(parentDir);
+  const byOrigin = {};
+  let unknown = 0;
+
+  for (const item of lista) {
+    if (item.origin === 'unknown') {
+      unknown++;
+    } else {
+      byOrigin[item.origin] = (byOrigin[item.origin] || 0) + 1;
+    }
+  }
+
+  return { total: lista.length, byOrigin, unknown };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  registrarProveniencia,
+  leerProveniencia,
+  listarProveniencias,
+  resumenProveniencia,
+  ORIGENES,
+  META_FILENAME,
+};

package/hooks/lib/raiz-proyecto.js

@@ -1,102 +1,158 @@
-'use strict';
-
-/**
- * raiz-proyecto.js — Resolución de la raíz del proyecto para hooks que
- * escriben telemetría/memoria en `.planning/`.
- *
- * El CWD de arranque de una sesión NO es la frontera del proyecto: en un
- * monorepo con sesiones abiertas en subdirectorios (`backend/`, `frontend/`),
- * anclar `.planning/` a `process.cwd()` fragmenta la memoria del proyecto en
- * árboles huérfanos (DT-HOOKS-RAIZ-GIT; misma clase que el fix de
- * proteccion-rutas). La frontera correcta es la raíz del repositorio git,
- * con una excepción: un sub-proyecto anidado que ya tiene su propio
- * `.planning/` REAL (con marcadores de proyecto) conserva su árbol local.
- *
- * Reglas de resolución (en orden):
- *   1. Ascendiendo desde `desde`, el primer directorio cuyo `.planning/`
- *      contiene un marcador de proyecto (PROYECTO.md, HOJA-RUTA.md,
- *      ESTADO.md) gana — respeta sub-proyectos legítimos en monorepos.
- *      Un `.planning/` sin marcadores (solo telemetría huérfana de hooks)
- *      NO cuenta: eso es el síntoma del bug, no un proyecto.
- *   2. Si ningún nivel tiene `.planning/` real, gana la raíz del repo git
- *      (`.git` como directorio o como archivo — worktrees).
- *   3. Sin `.git` alcanzable: fallback al propio `desde`.
- *
- * La ascensión se detiene en el HOME del usuario (sin incluirlo) cuando se
- * llega ahí subiendo: un dotfiles-repo en `~` no debe capturar la memoria
- * de un proyecto sin git que viva debajo.
- *
- * Zero-deps (regla de hooks/lib/). Consumidor inicial:
- * hooks/extraccion-aprendizajes.js; la flota completa migró el 2026-07-10
- * (cierre de DT-HOOKS-RAIZ-GIT).
- *
- * LÍMITE DE USO (hallazgo revisor-seguridad 2026-07-10): esta ancla es SOLO
- * para DATOS (.planning/, instintos/, lecturas de config del proyecto).
- * NUNCA resolver con ella EJECUTABLES ni módulos a require()/spawn(): la
- * raíz resuelta pertenece al árbol del proyecto, y un repositorio no
- * confiable puede plantar el script (marcador .planning/PROYECTO.md +
- * scripts/x.js hostil = ejecución de código al disparar el hook). Los
- * ejecutables de la distribución SWL se resuelven desde __dirname
- * (ubicación instalada del hook). Test guardián:
- * tests/hooks/ejecutables-desde-instalacion.test.js.
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-const MARCADORES_PROYECTO = ['PROYECTO.md', 'HOJA-RUTA.md', 'ESTADO.md'];
-const MAX_NIVELES = 40;
-
-/**
- * ¿El directorio tiene un `.planning/` de proyecto real (no huérfano)?
- * @param {string} dir
- * @returns {boolean}
- */
-function tienePlanningReal(dir) {
-  try {
-    return MARCADORES_PROYECTO.some(m =>
-      fs.existsSync(path.join(dir, '.planning', m))
-    );
-  } catch (_) {
-    return false;
-  }
-}
-
-/**
- * Resuelve la raíz del proyecto a la que deben anclarse las escrituras
- * de `.planning/`.
- *
- * @param {string} [desde] - Directorio de partida (default: process.cwd()).
- * @returns {string} Ruta absoluta de la raíz del proyecto.
- */
-function raizProyecto(desde) {
-  const inicio = path.resolve(desde || process.cwd());
-  let actual = inicio;
-  let homedir = null;
-  try {
-    homedir = path.resolve(os.homedir());
-  } catch (_) { /* sin home resolvible — seguir sin el guard */ }
-
-  for (let i = 0; i < MAX_NIVELES; i++) {
-    // Frontera del HOME: si llegamos aquí ASCENDIENDO, no seguir — un
-    // dotfiles-repo en ~ no es la raíz de un proyecto que vive debajo.
-    if (homedir && actual === homedir && i > 0) break;
-
-    if (tienePlanningReal(actual)) return actual;
-
-    try {
-      if (fs.existsSync(path.join(actual, '.git'))) return actual;
-    } catch (_) {
-      break;
-    }
-
-    const padre = path.dirname(actual);
-    if (padre === actual) break; // raíz del filesystem
-    actual = padre;
-  }
-
-  return inicio;
-}
-
-module.exports = { raizProyecto, tienePlanningReal };
+'use strict';
+
+/**
+ * raiz-proyecto.js — Resolución de la raíz del proyecto para hooks que
+ * escriben telemetría/memoria en `.planning/`.
+ *
+ * El CWD de arranque de una sesión NO es la frontera del proyecto: en un
+ * monorepo con sesiones abiertas en subdirectorios (`backend/`, `frontend/`),
+ * anclar `.planning/` a `process.cwd()` fragmenta la memoria del proyecto en
+ * árboles huérfanos (DT-HOOKS-RAIZ-GIT; misma clase que el fix de
+ * proteccion-rutas). La frontera correcta es la raíz del repositorio git,
+ * con una excepción: un sub-proyecto anidado que ya tiene su propio
+ * `.planning/` REAL (con marcadores de proyecto) conserva su árbol local.
+ *
+ * Reglas de resolución (en orden):
+ *   1. Ascendiendo desde `desde`, el primer directorio cuyo `.planning/`
+ *      contiene un marcador de proyecto (PROYECTO.md, HOJA-RUTA.md,
+ *      ESTADO.md) gana — respeta sub-proyectos legítimos en monorepos.
+ *      Un `.planning/` sin marcadores (solo telemetría huérfana de hooks)
+ *      NO cuenta: eso es el síntoma del bug, no un proyecto.
+ *   2. Si ningún nivel tiene `.planning/` real, gana la raíz del repo git
+ *      (`.git` como directorio o como archivo — worktrees).
+ *   3. Sin `.git` alcanzable: fallback al propio `desde`.
+ *
+ * La ascensión se detiene en el HOME del usuario (sin incluirlo) cuando se
+ * llega ahí subiendo: un dotfiles-repo en `~` — o un `~/.planning` sembrado
+ * por `swl-ses doctor` en una instalación global — no debe capturar la
+ * memoria de un proyecto sin git que viva debajo. La comparación con el HOME
+ * se hace en forma CANÓNICA (realpath): en Windows `os.tmpdir()` puede
+ * devolver el nombre corto 8.3 (`C:\Users\SAUL~1.WAD`) mientras `os.homedir()`
+ * devuelve el largo (`C:\Users\saul.wade`); sin canonicalizar, la frontera no
+ * dispararía y capturaría `~/.planning` o `~/.git` (rompía 38 tests locales
+ * en Windows, verde en CI Linux porque `/tmp` no cuelga de `$HOME`).
+ *
+ * Zero-deps (regla de hooks/lib/). Consumidor inicial:
+ * hooks/extraccion-aprendizajes.js; la flota completa migró el 2026-07-10
+ * (cierre de DT-HOOKS-RAIZ-GIT).
+ *
+ * LÍMITE DE USO (hallazgo revisor-seguridad 2026-07-10): esta ancla es SOLO
+ * para DATOS (.planning/, instintos/, lecturas de config del proyecto).
+ * NUNCA resolver con ella EJECUTABLES ni módulos a require()/spawn(): la
+ * raíz resuelta pertenece al árbol del proyecto, y un repositorio no
+ * confiable puede plantar el script (marcador .planning/PROYECTO.md +
+ * scripts/x.js hostil = ejecución de código al disparar el hook). Los
+ * ejecutables de la distribución SWL se resuelven desde __dirname
+ * (ubicación instalada del hook). Test guardián:
+ * tests/hooks/ejecutables-desde-instalacion.test.js.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const MARCADORES_PROYECTO = ['PROYECTO.md', 'HOJA-RUTA.md', 'ESTADO.md'];
+const MAX_NIVELES = 40;
+
+/**
+ * ¿El directorio tiene un `.planning/` de proyecto real (no huérfano)?
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function tienePlanningReal(dir) {
+  try {
+    return MARCADORES_PROYECTO.some(m =>
+      fs.existsSync(path.join(dir, '.planning', m))
+    );
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Canonicaliza un path resolviendo enlaces simbólicos y el nombre corto 8.3
+ * de Windows (`C:\Users\SAUL~1.WAD` → `C:\Users\saul.wade`). Solo se usa para
+ * la comparación de la frontera del HOME: el valor de RETORNO de raizProyecto
+ * conserva la forma del argumento recibido, no la canónica. Si el path no
+ * existe (no se puede resolver), cae a `path.resolve`.
+ * @param {string} p
+ * @returns {string}
+ */
+function canonicalizar(p) {
+  try {
+    return fs.realpathSync.native(p);
+  } catch (_) {
+    return path.resolve(p);
+  }
+}
+
+/**
+ * Ancla base: asciende desde `desde` buscando la raíz del proyecto (marcadores
+ * o `.git`), con frontera del HOME. Ver reglas de resolución en el docstring
+ * del módulo. Sin post-proceso de redirección (eso lo hace raizProyecto).
+ *
+ * @param {string} [desde] - Directorio de partida (default: process.cwd()).
+ * @returns {string} Ruta absoluta del ancla base.
+ */
+function _anclaBase(desde) {
+  const inicio = path.resolve(desde || process.cwd());
+  let actual = inicio;
+  let homedirCanon = null;
+  try {
+    homedirCanon = canonicalizar(path.resolve(os.homedir()));
+  } catch (_) { /* sin home resolvible — seguir sin el guard */ }
+
+  for (let i = 0; i < MAX_NIVELES; i++) {
+    // Frontera del HOME: si llegamos aquí ASCENDIENDO, no seguir — un
+    // dotfiles-repo (o un ~/.planning sembrado por doctor) en ~ no es la raíz
+    // de un proyecto que vive debajo. Comparación canónica: iguala el nombre
+    // corto 8.3 heredado de os.tmpdir() con el HOME largo de os.homedir().
+    if (homedirCanon && i > 0 && canonicalizar(actual) === homedirCanon) break;
+
+    if (tienePlanningReal(actual)) return actual;
+
+    try {
+      if (fs.existsSync(path.join(actual, '.git'))) return actual;
+    } catch (_) {
+      break;
+    }
+
+    const padre = path.dirname(actual);
+    if (padre === actual) break; // raíz del filesystem
+    actual = padre;
+  }
+
+  return inicio;
+}
+
+/**
+ * Resuelve la raíz del proyecto a la que deben anclarse las escrituras
+ * de `.planning/`.
+ *
+ * Redirección de telemetría (fix 2026-07-15): si el ancla resuelta es el HOME
+ * del usuario y el HOME NO es un proyecto SWL real (solo un `.git` de dotfiles
+ * o un fallback sin proyecto), NINGÚN hook debe sembrar `.planning/` en la raíz
+ * del HOME — se contiene en `~/.claude/` (mismo scope que los backups del
+ * install global, A3). Esto arregla los 33 hooks que anclan vía esta función
+ * en un solo punto, sin tocarlos. Un proyecto SWL real EN el HOME (con
+ * marcadores de proyecto) se respeta.
+ *
+ * @param {string} [desde] - Directorio de partida (default: process.cwd()).
+ * @returns {string} Ruta absoluta de la raíz del proyecto (o ~/.claude si el
+ *   HOME no es un proyecto).
+ */
+function raizProyecto(desde) {
+  const raiz = _anclaBase(desde);
+  let homedirCanon = null;
+  try {
+    homedirCanon = canonicalizar(path.resolve(os.homedir()));
+  } catch (_) {
+    return raiz; // sin home resolvible — no redirigir
+  }
+  if (canonicalizar(raiz) === homedirCanon && !tienePlanningReal(raiz)) {
+    try { return path.join(os.homedir(), '.claude'); } catch (_) { return raiz; }
+  }
+  return raiz;
+}
+
+module.exports = { raizProyecto, tienePlanningReal, canonicalizar };