@saulwade/swl-ses 1.6.1 → 1.6.3

package/schemas/skill-frontmatter.schema.json

@@ -1,170 +1,245 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://swl-ses.dev/schemas/skill-frontmatter.json",
-  "title": "SWL Skill Frontmatter",
-  "description": "Schema de validacion para el frontmatter YAML de skills del sistema SWL",
-  "type": "object",
-  "required": ["name", "description"],
-  "properties": {
-    "name": {
-      "type": "string",
-      "pattern": "^[a-z][a-z0-9-]+$",
-      "maxLength": 64,
-      "description": "Nombre en kebab-case que coincide con el directorio"
-    },
-    "description": {
-      "type": "string",
-      "minLength": 20,
-      "maxLength": 1024,
-      "description": "Descripcion que incluye QUE hace y CUANDO cargarla"
-    },
-    "version": {
-      "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$"
-    },
-    "provenance": {
-      "type": "object",
-      "description": "Campo legacy. Equivalente espanol: 'procedencia'. Si ambos presentes deben coincidir (W010).",
-      "properties": {
-        "origin": {
-          "type": "string",
-          "enum": ["manual", "auto-evolution", "imported", "community"]
-        },
-        "created_at": {
-          "type": "string",
-          "format": "date"
-        },
-        "confidence": {
-          "type": "number",
-          "minimum": 0,
-          "maximum": 1
-        },
-        "author": {
-          "type": "string"
-        }
-      }
-    },
-    "procedencia": {
-      "type": "object",
-      "description": "Alias en espanol de 'provenance'. Campo propio de swl-ses. Si ambos presentes, deben coincidir (W010).",
-      "properties": {
-        "origin": {
-          "type": "string",
-          "enum": ["manual", "auto-evolution", "imported", "community"]
-        },
-        "created_at": {
-          "type": "string",
-          "format": "date"
-        },
-        "confidence": {
-          "type": "number",
-          "minimum": 0,
-          "maximum": 1
-        },
-        "author": {
-          "type": "string"
-        }
-      }
-    },
-    "targets": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["claude", "openclaude", "copilot", "opencode", "codex", "gemini"]
-      },
-      "description": "Campo legacy. Equivalente espanol: 'destinos'. Runtimes a los que se sincroniza este skill. Patron adoptado de skillshare (targets.yaml). Si ambos presentes deben coincidir (W010)."
-    },
-    "destinos": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["claude", "openclaude", "copilot", "opencode", "codex", "gemini"]
-      },
-      "description": "Alias en espanol de 'targets'. Campo propio de swl-ses. Runtimes a los que se sincroniza este skill."
-    },
-    "user-invocable": {
-      "type": "boolean",
-      "description": "Si el usuario puede invocar este skill directamente con Skill(nombre)"
-    },
-    "license": {
-      "type": "string",
-      "description": "Licencia del skill si es externo o adaptado"
-    },
-    "evolvable": {
-      "type": "boolean",
-      "description": "Campo legacy. Equivalente espanol: 'evolucionable'. Marca AGP learnability. Si false, el loop de auto-evolucion NO debe proponer cambios a este skill. Recomendado: false para skills criticos. Si ambos presentes deben coincidir (W010)."
-    },
-    "evolucionable": {
-      "type": "boolean",
-      "description": "Alias en espanol de 'evolvable'. Campo propio de swl-ses. Marca AGP learnability. Si false, el loop de auto-evolucion NO propone cambios a este skill."
-    },
-    "evolvable_scope": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["description", "content", "examples", "references", "anti-patterns"]
-      },
-      "description": "Campo legacy. Equivalente espanol: 'evolucionable_alcance'. Si evolvable=true, limita las secciones del SKILL.md que pueden modificarse. Ausente implica 'content' y 'examples' unicamente. Si ambos presentes deben coincidir (W010)."
-    },
-    "evolucionable_alcance": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["description", "content", "examples", "references", "anti-patterns"]
-      },
-      "description": "Alias en espanol de 'evolvable_scope'. Campo propio de swl-ses. Si evolucionable=true, limita las secciones modificables."
-    },
-    "when_to_use": {
-      "type": "string",
-      "maxLength": 512,
-      "description": "Campo del protocolo Anthropic. Contexto adicional sobre cuando activar la skill, leido por Claude Code como bloque combinado con description (total max 1536 chars). Usar cuando description ocupa mas de 900 chars y aun hay triggers que no caben."
-    },
-    "exclusiones": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Situaciones donde esta skill NO debe activarse aunque parezca relevante superficialmente. Campo propio de swl-ses; previene skill hijacking por similitud de terminos. Equivalente estructural de la seccion 'Cuando NO cargar' en el cuerpo de SKILL.md, legible por herramientas de analisis sin parsear markdown."
-    },
-    "allowed-tools": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "WebSearch", "WebFetch"]
-      },
-      "description": "Campo del protocolo Anthropic. Pre-aprobacion de UX leida por Claude Code. NO es restriccion de seguridad real. Las restricciones reales provienen de permission rules en .claude/settings.json o del matcher en hooks."
-    },
-    "herramientasPermitidas": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "WebSearch", "WebFetch"]
-      },
-      "description": "Campo propio de swl-ses. Alias semantico de allowed-tools, usado por las herramientas internas (evaluar-skill, validadores). Debe coincidir con allowed-tools cuando ambos estan presentes. Si divergen, el validador emite W011. Para skills nuevos en swl-ses, declarar solo este campo; una herramienta de sincronizacion propagara el valor a allowed-tools al construir artefactos para Claude Code."
-    },
-    "nist_csf": {
-      "type": "array",
-      "items": { "type": "string", "pattern": "^(GV|ID|PR|DE|RS|RC)\\.[A-Z]{2}(-[0-9]{2})?$" },
-      "description": "Campo propio de swl-ses. Mapeo a NIST Cybersecurity Framework 2.0. Cada entrada es un ID de subcategoria tipo 'GV.SC-07', 'PR.PS-01', 'DE.CM-01'. Opcional. Usado para reportes de cobertura en /swl:salud y /swl:dashboard. Referencia: https://www.nist.gov/cyberframework"
-    },
-    "nist_ai_rmf": {
-      "type": "array",
-      "items": { "type": "string", "pattern": "^(GOVERN|MAP|MEASURE|MANAGE)(-[0-9]+(\\.[0-9]+)?)?$" },
-      "description": "Campo propio de swl-ses. Mapeo a NIST AI Risk Management Framework 1.0. Cada entrada es un ID de subcategoria tipo 'GOVERN-1.1', 'MAP-5.1', 'MEASURE-2.7'. Opcional. Particularmente relevante para skills de seguridad de sistemas agenticos. Referencia: https://airc.nist.gov/AI_RMF"
-    },
-    "atlas_techniques": {
-      "type": "array",
-      "items": { "type": "string", "pattern": "^AML\\.T[0-9]{4}(\\.[0-9]{3})?$" },
-      "description": "Campo propio de swl-ses. Mapeo a MITRE ATLAS v5.4 (Adversarial Threat Landscape for AI Systems). Cada entrada es una tecnica tipo 'AML.T0051' (LLM Prompt Injection), 'AML.T0080' (AI Agent Context Poisoning). Opcional. Critico para skills que protegen el sistema agentico mismo. Referencia: https://atlas.mitre.org"
-    },
-    "attack_techniques": {
-      "type": "array",
-      "items": { "type": "string", "pattern": "^T[0-9]{4}(\\.[0-9]{3})?$" },
-      "description": "Campo propio de swl-ses. Mapeo a MITRE ATT&CK v18. Cada entrada es una tecnica tipo 'T1071' (Application Layer Protocol), 'T1190' (Exploit Public-Facing Application). Opcional. Mas aplicable a skills de defensa de infraestructura o deteccion de amenazas en el sistema desplegado. Referencia: https://attack.mitre.org"
-    },
-    "d3fend_techniques": {
-      "type": "array",
-      "items": { "type": "string", "pattern": "^D3-[A-Z]+$" },
-      "description": "Campo propio de swl-ses. Mapeo a MITRE D3FEND v1.3 (Defensive countermeasures). Cada entrada es una tecnica tipo 'D3-NTA' (Network Traffic Analysis), 'D3-PSA' (Process Spawn Analysis). Opcional. Referencia: https://d3fend.mitre.org"
-    }
-  },
-  "additionalProperties": true
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://swl-ses.dev/schemas/skill-frontmatter.json",
+  "$schemaVersion": "1.0.0",
+  "title": "SWL Skill Frontmatter",
+  "description": "Schema de validacion para el frontmatter YAML de skills del sistema SWL",
+  "type": "object",
+  "required": [
+    "name",
+    "description"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]+$",
+      "maxLength": 64,
+      "description": "Nombre en kebab-case que coincide con el directorio"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 20,
+      "maxLength": 1024,
+      "description": "Descripcion que incluye QUE hace y CUANDO cargarla"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "provenance": {
+      "type": "object",
+      "description": "Campo legacy. Equivalente espanol: 'procedencia'. Si ambos presentes deben coincidir (W010).",
+      "properties": {
+        "origin": {
+          "type": "string",
+          "enum": [
+            "manual",
+            "auto-evolution",
+            "imported",
+            "community"
+          ]
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date"
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "author": {
+          "type": "string"
+        }
+      }
+    },
+    "procedencia": {
+      "type": "object",
+      "description": "Alias en espanol de 'provenance'. Campo propio de swl-ses. Si ambos presentes, deben coincidir (W010).",
+      "properties": {
+        "origin": {
+          "type": "string",
+          "enum": [
+            "manual",
+            "auto-evolution",
+            "imported",
+            "community"
+          ]
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date"
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "author": {
+          "type": "string"
+        }
+      }
+    },
+    "targets": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "claude",
+          "openclaude",
+          "copilot",
+          "opencode",
+          "codex",
+          "gemini"
+        ]
+      },
+      "description": "Campo legacy. Equivalente espanol: 'destinos'. Runtimes a los que se sincroniza este skill. Patron adoptado de skillshare (targets.yaml). Si ambos presentes deben coincidir (W010)."
+    },
+    "destinos": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "claude",
+          "openclaude",
+          "copilot",
+          "opencode",
+          "codex",
+          "gemini"
+        ]
+      },
+      "description": "Alias en espanol de 'targets'. Campo propio de swl-ses. Runtimes a los que se sincroniza este skill."
+    },
+    "user-invocable": {
+      "type": "boolean",
+      "description": "Si el usuario puede invocar este skill directamente con Skill(nombre)"
+    },
+    "license": {
+      "type": "string",
+      "description": "Licencia del skill si es externo o adaptado"
+    },
+    "evolvable": {
+      "type": "boolean",
+      "description": "Campo legacy. Equivalente espanol: 'evolucionable'. Marca AGP learnability. Si false, el loop de auto-evolucion NO debe proponer cambios a este skill. Recomendado: false para skills criticos. Si ambos presentes deben coincidir (W010)."
+    },
+    "evolucionable": {
+      "type": "boolean",
+      "description": "Alias en espanol de 'evolvable'. Campo propio de swl-ses. Marca AGP learnability. Si false, el loop de auto-evolucion NO propone cambios a este skill."
+    },
+    "evolvable_scope": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "description",
+          "content",
+          "examples",
+          "references",
+          "anti-patterns"
+        ]
+      },
+      "description": "Campo legacy. Equivalente espanol: 'evolucionable_alcance'. Si evolvable=true, limita las secciones del SKILL.md que pueden modificarse. Ausente implica 'content' y 'examples' unicamente. Si ambos presentes deben coincidir (W010)."
+    },
+    "evolucionable_alcance": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "description",
+          "content",
+          "examples",
+          "references",
+          "anti-patterns"
+        ]
+      },
+      "description": "Alias en espanol de 'evolvable_scope'. Campo propio de swl-ses. Si evolucionable=true, limita las secciones modificables."
+    },
+    "when_to_use": {
+      "type": "string",
+      "maxLength": 512,
+      "description": "Campo del protocolo Anthropic. Contexto adicional sobre cuando activar la skill, leido por Claude Code como bloque combinado con description (total max 1536 chars). Usar cuando description ocupa mas de 900 chars y aun hay triggers que no caben."
+    },
+    "exclusiones": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Situaciones donde esta skill NO debe activarse aunque parezca relevante superficialmente. Campo propio de swl-ses; previene skill hijacking por similitud de terminos. Equivalente estructural de la seccion 'Cuando NO cargar' en el cuerpo de SKILL.md, legible por herramientas de analisis sin parsear markdown."
+    },
+    "allowed-tools": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "Read",
+          "Write",
+          "Edit",
+          "Bash",
+          "Glob",
+          "Grep",
+          "WebSearch",
+          "WebFetch"
+        ]
+      },
+      "description": "Campo del protocolo Anthropic. Pre-aprobacion de UX leida por Claude Code. NO es restriccion de seguridad real. Las restricciones reales provienen de permission rules en .claude/settings.json o del matcher en hooks."
+    },
+    "herramientasPermitidas": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "Read",
+          "Write",
+          "Edit",
+          "Bash",
+          "Glob",
+          "Grep",
+          "WebSearch",
+          "WebFetch"
+        ]
+      },
+      "description": "Campo propio de swl-ses. Alias semantico de allowed-tools, usado por las herramientas internas (evaluar-skill, validadores). Debe coincidir con allowed-tools cuando ambos estan presentes. Si divergen, el validador emite W011. Para skills nuevos en swl-ses, declarar solo este campo; una herramienta de sincronizacion propagara el valor a allowed-tools al construir artefactos para Claude Code."
+    },
+    "nist_csf": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^(GV|ID|PR|DE|RS|RC)\\.[A-Z]{2}(-[0-9]{2})?$"
+      },
+      "description": "Campo propio de swl-ses. Mapeo a NIST Cybersecurity Framework 2.0. Cada entrada es un ID de subcategoria tipo 'GV.SC-07', 'PR.PS-01', 'DE.CM-01'. Opcional. Usado para reportes de cobertura en /swl:salud y /swl:dashboard. Referencia: https://www.nist.gov/cyberframework"
+    },
+    "nist_ai_rmf": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^(GOVERN|MAP|MEASURE|MANAGE)(-[0-9]+(\\.[0-9]+)?)?$"
+      },
+      "description": "Campo propio de swl-ses. Mapeo a NIST AI Risk Management Framework 1.0. Cada entrada es un ID de subcategoria tipo 'GOVERN-1.1', 'MAP-5.1', 'MEASURE-2.7'. Opcional. Particularmente relevante para skills de seguridad de sistemas agenticos. Referencia: https://airc.nist.gov/AI_RMF"
+    },
+    "atlas_techniques": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^AML\\.T[0-9]{4}(\\.[0-9]{3})?$"
+      },
+      "description": "Campo propio de swl-ses. Mapeo a MITRE ATLAS v5.4 (Adversarial Threat Landscape for AI Systems). Cada entrada es una tecnica tipo 'AML.T0051' (LLM Prompt Injection), 'AML.T0080' (AI Agent Context Poisoning). Opcional. Critico para skills que protegen el sistema agentico mismo. Referencia: https://atlas.mitre.org"
+    },
+    "attack_techniques": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^T[0-9]{4}(\\.[0-9]{3})?$"
+      },
+      "description": "Campo propio de swl-ses. Mapeo a MITRE ATT&CK v18. Cada entrada es una tecnica tipo 'T1071' (Application Layer Protocol), 'T1190' (Exploit Public-Facing Application). Opcional. Mas aplicable a skills de defensa de infraestructura o deteccion de amenazas en el sistema desplegado. Referencia: https://attack.mitre.org"
+    },
+    "d3fend_techniques": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^D3-[A-Z]+$"
+      },
+      "description": "Campo propio de swl-ses. Mapeo a MITRE D3FEND v1.3 (Defensive countermeasures). Cada entrada es una tecnica tipo 'D3-NTA' (Network Traffic Analysis), 'D3-PSA' (Process Spawn Analysis). Opcional. Referencia: https://d3fend.mitre.org"
+    }
+  },
+  "additionalProperties": true
+}

package/scripts/generar-inventario.js

@@ -82,7 +82,9 @@ function contarSkills(dir) {
 
 function recolectarAgentes() {
   const dir = path.join(RAIZ, 'agentes');
-  const archivos = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+  // Excluir fragmentos compartidos (`_*.md`) — no son agentes routables.
+  // Ver reglas/fragmentos-compartidos.md.
+  const archivos = fs.readdirSync(dir).filter(f => f.endsWith('.md') && !f.startsWith('_'));
   return archivos.map(f => {
     const fm = leerFrontmatter(path.join(dir, f));
     return {

package/scripts/lib/schema-version.js

@@ -0,0 +1,164 @@
+'use strict';
+
+/**
+ * scripts/lib/schema-version.js
+ *
+ * Helper de compatibilidad de schemas JSON aplicando reglas backward/forward
+ * del libro "Designing Data-Intensive Applications" de Martin Kleppmann
+ * (Capítulo 4, "Encoding and Evolution", p.112).
+ *
+ * Reglas implementadas (cita textual del libro):
+ *
+ *   "Backward compatibility — Newer code can read data that was written by
+ *    older code.
+ *
+ *    Forward compatibility — Older code can read data that was written by
+ *    newer code."
+ *
+ * Aplicado a SWL: cuando un schema evoluciona, el helper indica si un
+ * documento dado puede leerse con el schema dado y bajo qué modalidad
+ * de compatibilidad.
+ *
+ * Convenciones SemVer asumidas para $schemaVersion:
+ *   - MAJOR (X.0.0): breaking change (renombre, cambio de tipo, eliminación)
+ *   - MINOR (1.X.0): campo nuevo opcional, enum value nuevo
+ *   - PATCH (1.0.X): clarificación de descripción, sin cambio estructural
+ *
+ * Skill relacionado: proceso-ddia-fundamentos § Schema Evolution.
+ * ADR: 0026 — Versionado de schemas JSON con $schemaVersion.
+ */
+
+/**
+ * Parsea un string SemVer "MAJOR.MINOR.PATCH" a tupla numérica.
+ * @param {string} version
+ * @returns {[number, number, number] | null}
+ */
+function parsearVersion(version) {
+  if (typeof version !== 'string') return null;
+  const m = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!m) return null;
+  return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)];
+}
+
+/**
+ * Verifica si un documento es compatible con un schema según sus $schemaVersion.
+ *
+ * @param {object} documento - Documento JSON con propiedad opcional $schemaVersion
+ * @param {object} schema - JSON Schema con propiedad opcional $schemaVersion
+ * @returns {{
+ *   compatible: boolean,
+ *   modo: "none" | "backward" | "forward" | "incompatible",
+ *   advertencias: string[]
+ * }}
+ *
+ * Casos:
+ *   - Ambos sin $schemaVersion → { compatible: true, modo: "none", advertencias: [warning] }
+ *   - Documento sin, schema con  → { compatible: true, modo: "forward", advertencias: [warning] }
+ *   - Doc 1.0.0 vs Schema 1.0.0  → { compatible: true, modo: "none" }
+ *   - Doc 1.0.0 vs Schema 1.1.0  → { compatible: true, modo: "forward" } (dato viejo + código nuevo)
+ *   - Doc 1.1.0 vs Schema 1.0.0  → { compatible: true, modo: "backward" } (dato nuevo + código viejo)
+ *   - Doc 2.0.0 vs Schema 1.0.0  → { compatible: false, modo: "incompatible" } (MAJOR rompe)
+ *   - Doc 1.0.0 vs Schema 2.0.0  → { compatible: false, modo: "incompatible" }
+ *   - Versión malformada         → { compatible: false, modo: "incompatible", advertencias: [error] }
+ */
+function verificarCompatibilidad(documento, schema) {
+  const advertencias = [];
+
+  const docVerStr = documento && documento.$schemaVersion;
+  const schVerStr = schema && schema.$schemaVersion;
+
+  if (!docVerStr && !schVerStr) {
+    return {
+      compatible: true,
+      modo: 'none',
+      advertencias: [
+        'Ni documento ni schema declaran $schemaVersion. Compatibilidad asumida pero no verificable.',
+      ],
+    };
+  }
+
+  if (!docVerStr && schVerStr) {
+    return {
+      compatible: true,
+      modo: 'forward',
+      advertencias: [
+        `Documento sin $schemaVersion contra schema ${schVerStr}. Asumiendo forward-compat (código nuevo lee dato viejo sin versión).`,
+      ],
+    };
+  }
+
+  if (docVerStr && !schVerStr) {
+    return {
+      compatible: false,
+      modo: 'incompatible',
+      advertencias: [
+        `Documento declara $schemaVersion ${docVerStr} pero schema no la declara. Schema debe actualizarse a $schemaVersion para validación correcta.`,
+      ],
+    };
+  }
+
+  const docVer = parsearVersion(docVerStr);
+  const schVer = parsearVersion(schVerStr);
+
+  if (!docVer) {
+    return {
+      compatible: false,
+      modo: 'incompatible',
+      advertencias: [`Documento $schemaVersion malformada: "${docVerStr}". Debe ser MAJOR.MINOR.PATCH (ej: "1.0.0").`],
+    };
+  }
+  if (!schVer) {
+    return {
+      compatible: false,
+      modo: 'incompatible',
+      advertencias: [`Schema $schemaVersion malformada: "${schVerStr}". Debe ser MAJOR.MINOR.PATCH (ej: "1.0.0").`],
+    };
+  }
+
+  const [docMaj, docMin] = docVer;
+  const [schMaj, schMin] = schVer;
+
+  // MAJOR distinto → incompatible (regla DDIA Cap 4: MAJOR es breaking)
+  if (docMaj !== schMaj) {
+    return {
+      compatible: false,
+      modo: 'incompatible',
+      advertencias: [
+        `MAJOR diferente: documento ${docVerStr} vs schema ${schVerStr}. ` +
+        `Cambios MAJOR son breaking por convención SemVer. Migración explícita requerida.`,
+      ],
+    };
+  }
+
+  // Mismo MAJOR.MINOR → compatible total (PATCH no afecta estructura)
+  if (docMin === schMin) {
+    return { compatible: true, modo: 'none', advertencias: [] };
+  }
+
+  // Documento MINOR menor que schema → forward (código nuevo lee dato viejo)
+  if (docMin < schMin) {
+    return {
+      compatible: true,
+      modo: 'forward',
+      advertencias: [
+        `Documento ${docVerStr} más antiguo que schema ${schVerStr}. ` +
+        `Forward-compat: código nuevo debe ignorar campos nuevos ausentes en dato viejo.`,
+      ],
+    };
+  }
+
+  // Documento MINOR mayor que schema → backward (código viejo lee dato nuevo)
+  return {
+    compatible: true,
+    modo: 'backward',
+    advertencias: [
+      `Documento ${docVerStr} más nuevo que schema ${schVerStr}. ` +
+      `Backward-compat: código viejo debe ignorar campos desconocidos en dato nuevo.`,
+    ],
+  };
+}
+
+module.exports = {
+  parsearVersion,
+  verificarCompatibilidad,
+};

package/scripts/validar-manifest.js

@@ -188,7 +188,7 @@ function main() {
   const categorias = [
     { etiqueta: 'comandos/swl/',       archivos: listarArchivos('comandos/swl', '.md') },
     { etiqueta: 'hooks/ (ejecutables)', archivos: hooksEjecutables },
-    { etiqueta: 'agentes/',             archivos: listarArchivos('agentes', '.md') },
+    { etiqueta: 'agentes/',             archivos: listarArchivos('agentes', '.md').filter(a => !path.basename(a).startsWith('_')) },
     { etiqueta: 'habilidades/ (dirs)',  archivos: listarDirectoriosHabilidades() },
     { etiqueta: 'reglas/',              archivos: listarArchivos('reglas', '.md', true) },
   ];

package/scripts/validar.js

@@ -63,8 +63,9 @@ if (fs.existsSync(hooksConfigPath)) {
   }
 }
 
-// 5. Agentes (mínimo 12)
-const agentes = fs.readdirSync(path.join(RAIZ, 'agentes')).filter(f => f.endsWith('.md'));
+// 5. Agentes (mínimo 12) — excluye fragmentos compartidos (`_*.md`, ver `reglas/fragmentos-compartidos.md`)
+const agentes = fs.readdirSync(path.join(RAIZ, 'agentes'))
+  .filter(f => f.endsWith('.md') && !f.startsWith('_'));
 verificar(agentes.length >= 12, `Agentes: ${agentes.length} (mínimo 12)`);
 
 // Verificar frontmatter en agentes