@saulwade/swl-ses 1.6.1 → 1.6.3

package/schemas/agent-frontmatter.schema.json

@@ -1,167 +1,294 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://swl-ses.dev/schemas/agent-frontmatter.json",
-  "title": "SWL Agent Frontmatter",
-  "description": "Schema de validacion para el frontmatter YAML de agentes del sistema SWL",
-  "type": "object",
-  "required": ["name", "description", "tools", "model", "version", "nivelRiesgo"],
-  "properties": {
-    "name": {
-      "type": "string",
-      "pattern": "^[a-z][a-z0-9-]+-swl$",
-      "maxLength": 64,
-      "description": "Nombre en kebab-case terminado en -swl"
-    },
-    "description": {
-      "type": "string",
-      "minLength": 20,
-      "maxLength": 1024,
-      "description": "Descripcion que incluye QUE hace y CUANDO invocarlo"
-    },
-    "tools": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "Agent", "Skill", "WebSearch", "WebFetch"]
-      },
-      "minItems": 1,
-      "description": "Herramientas permitidas para este agente"
-    },
-    "model": {
-      "type": "string",
-      "oneOf": [
-        { "enum": ["opus", "sonnet", "haiku", "inherit"] },
-        { "pattern": "^claude-(opus|sonnet|haiku)-[0-9]+-[0-9]+(-[0-9]+)?$" }
-      ],
-      "description": "Modelo principal del agente. Acepta alias cortos (opus/sonnet/haiku), 'inherit' para sub-agentes, o nombre completo tipo 'claude-opus-4-7', 'claude-sonnet-4-6', 'claude-haiku-4-5-20251001'."
-    },
-    "modeloAlterno": {
-      "type": "string",
-      "oneOf": [
-        { "enum": ["opus", "sonnet", "haiku", "inherit"] },
-        { "pattern": "^claude-(opus|sonnet|haiku)-[0-9]+-[0-9]+(-[0-9]+)?$" }
-      ],
-      "description": "Modelo alternativo cuando el principal no esta disponible. Mismos formatos aceptados que 'model'."
-    },
-    "ventanaContexto": {
-      "type": "string",
-      "description": "Ventana de contexto recomendada"
-    },
-    "version": {
-      "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$",
-      "description": "Version semantica del agente"
-    },
-    "nivelRiesgo": {
-      "type": "string",
-      "enum": ["BAJO", "MEDIO", "ALTO"],
-      "description": "Nivel de riesgo de las operaciones del agente"
-    },
-    "skillsInvocables": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Skills que este agente puede invocar. Valor especial 'todos' = wildcard (sin restriccion de skill); usar solo en agentes generalistas (investigador-swl, planificador-swl) cuando listar 162 skills es impractico. Para todos los demas agentes, listar skills especificos siguiendo privilegio minimo (regla seguridad-agentes.md)."
-    },
-    "skillsRestringidos": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Skills que este agente NO debe invocar"
-    },
-    "permisosRed": {
-      "type": "boolean",
-      "description": "Si el agente puede hacer llamadas de red"
-    },
-    "permisosEscritura": {
-      "type": "boolean",
-      "description": "Si el agente puede escribir archivos"
-    },
-    "permisosComandos": {
-      "type": "boolean",
-      "description": "Si el agente puede ejecutar comandos bash"
-    },
-    "presupuestoMaxUsd": {
-      "type": "number",
-      "minimum": 0.01,
-      "maximum": 50.0,
-      "description": "Presupuesto maximo en USD por invocacion del agente. Inspirado en maxBudgetUsd del Anthropic Agent SDK. El hook tracking-costos emite alerta al 80% y sugiere detener al 100%"
-    },
-    "maxTurnos": {
-      "type": "integer",
-      "minimum": 1,
-      "maximum": 100,
-      "description": "Maximo de turnos (iteraciones de herramienta) por invocacion. Previene loops infinitos. Inspirado en maxTurns del Anthropic Agent SDK"
-    },
-    "toolBudget": {
-      "type": "object",
-      "properties": {
-        "simple": { "type": "integer", "description": "Tool calls para tareas simples" },
-        "standard": { "type": "integer", "description": "Tool calls para tareas estandar" },
-        "complex": { "type": "integer", "description": "Tool calls para tareas complejas" }
-      },
-      "description": "Presupuesto de tool calls por nivel de complejidad"
-    },
-    "evolvable": {
-      "type": "boolean",
-      "description": "Marca AGP learnability. Si false, el loop de auto-evolucion NO debe proponer cambios a este agente. Default implicito (ausencia del campo): true para BAJO, false para MEDIO/ALTO."
-    },
-    "evolvable_scope": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["description", "examples", "instructions", "skillsInvocables", "skillsRestringidos", "tools", "model", "nivelRiesgo", "permisosRed", "permisosEscritura", "permisosComandos"]
-      },
-      "description": "Si evolvable=true, limita las secciones/campos que el loop puede modificar. Ausente implica 'description' y 'examples' unicamente — campos de seguridad NUNCA evolucionan sin aprobacion humana."
-    },
-    "invariantes": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["campo", "operador", "valor"],
-        "properties": {
-          "campo": {
-            "type": "string",
-            "description": "Nombre de la propiedad del frontmatter a validar tras una evolucion (ej: 'permisosRed')."
-          },
-          "operador": {
-            "type": "string",
-            "enum": ["eq", "neq", "lte", "gte", "in", "not_in"],
-            "description": "Operador de comparacion. eq/neq: igualdad; lte/gte: orden numerico; in/not_in: pertenencia a lista."
-          },
-          "valor": {
-            "description": "Valor esperado. Para in/not_in debe ser array."
-          },
-          "razon": {
-            "type": "string",
-            "description": "Justificacion humana del invariante. Opcional pero recomendado."
-          }
-        },
-        "additionalProperties": false
-      },
-      "description": "Safety invariants que el commit gate (run-skill-evals.js) debe verificar tras cada evolucion."
-    },
-    "exclusiones": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Situaciones donde este agente NO debe invocarse aunque parezca relevante superficialmente. Campo propio de swl-ses; previene activacion tangencial (agent hijacking) por similitud de terminos en description. Equivalente estructural de la seccion 'Cuando NO invocarme' en el cuerpo, legible por herramientas de analisis sin parsear markdown. Aditivo, no breaking, aplicable a agentes con evolvable:false (metadata defensiva, no evolucion AGP — ver ADR-0004)."
-    },
-    "fase": {
-      "type": "string",
-      "enum": ["discover", "plan", "implement", "verify", "release", "learn", "meta", "cross"],
-      "description": "Fase del SDLC en que opera el agente. Vocabulario controlado para routing deterministico del orquestador sin parsear description. discover=research/UX/discovery; plan=arquitectura/planificacion; implement=codigo/implementacion; verify=revision/testing/seguridad; release=deploy/release; learn=auto-evolucion/aprendizaje; meta=componentes del sistema SWL mismo; cross=transversal a varias fases. Aditivo, opcional. Inspirado en patron Phase de Bug-Bounty-Agents/AGENTS.md y patron Workflow-vs-Agent del articulo Anthropic 'Building Effective AI Agents'."
-    },
-    "dominio": {
-      "type": "string",
-      "enum": ["backend", "frontend", "mobile", "data", "infra", "security", "ux", "quality", "docs", "process", "meta", "general"],
-      "description": "Dominio tecnico primario del agente. Vocabulario controlado para filtrado y matching. backend=APIs/servidores; frontend=UI/web; mobile=Android/iOS/cross; data=BD/ETL/datos; infra=cloud/CI/devops; security=auditoria/OWASP; ux=diseno/usabilidad; quality=tests/QA/code review; docs=documentacion; process=workflow/orquestacion; meta=sistema SWL; general=transversal. Aditivo, opcional."
-    },
-    "fragmentos": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "pattern": "^_[a-z][a-z0-9-]*$"
-      },
-      "description": "Lista de bloques de prompt compartidos no-routables (archivos agentes/_*.md) que este agente importa literalmente en su system prompt. Permite centralizar texto repetido entre multiples agentes sin duplicacion. Los fragmentos NO son skills (no se invocan dinamicamente) ni agentes (no son routables por el orquestador). Convencion: prefijo _ en kebab-case, sin sufijo -swl. Ejemplo: ['_brevedad-output-ref', '_hitl-alto-riesgo']. Inspirado en patron _scope-guard.md de Bug-Bounty-Agents."
-    }
-  },
-  "additionalProperties": true
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://swl-ses.dev/schemas/agent-frontmatter.json",
+  "$schemaVersion": "1.0.0",
+  "title": "SWL Agent Frontmatter",
+  "description": "Schema de validacion para el frontmatter YAML de agentes del sistema SWL",
+  "type": "object",
+  "required": [
+    "name",
+    "description",
+    "tools",
+    "model",
+    "version",
+    "nivelRiesgo"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]+-swl$",
+      "maxLength": 64,
+      "description": "Nombre en kebab-case terminado en -swl"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 20,
+      "maxLength": 1024,
+      "description": "Descripcion que incluye QUE hace y CUANDO invocarlo"
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "Read",
+          "Write",
+          "Edit",
+          "Bash",
+          "Grep",
+          "Glob",
+          "Agent",
+          "Skill",
+          "WebSearch",
+          "WebFetch"
+        ]
+      },
+      "minItems": 1,
+      "description": "Herramientas permitidas para este agente"
+    },
+    "model": {
+      "type": "string",
+      "oneOf": [
+        {
+          "enum": [
+            "opus",
+            "sonnet",
+            "haiku",
+            "inherit"
+          ]
+        },
+        {
+          "pattern": "^claude-(opus|sonnet|haiku)-[0-9]+-[0-9]+(-[0-9]+)?$"
+        }
+      ],
+      "description": "Modelo principal del agente. Acepta alias cortos (opus/sonnet/haiku), 'inherit' para sub-agentes, o nombre completo tipo 'claude-opus-4-7', 'claude-sonnet-4-6', 'claude-haiku-4-5-20251001'."
+    },
+    "modeloAlterno": {
+      "type": "string",
+      "oneOf": [
+        {
+          "enum": [
+            "opus",
+            "sonnet",
+            "haiku",
+            "inherit"
+          ]
+        },
+        {
+          "pattern": "^claude-(opus|sonnet|haiku)-[0-9]+-[0-9]+(-[0-9]+)?$"
+        }
+      ],
+      "description": "Modelo alternativo cuando el principal no esta disponible. Mismos formatos aceptados que 'model'."
+    },
+    "ventanaContexto": {
+      "type": "string",
+      "description": "Ventana de contexto recomendada"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Version semantica del agente"
+    },
+    "nivelRiesgo": {
+      "type": "string",
+      "enum": [
+        "BAJO",
+        "MEDIO",
+        "ALTO"
+      ],
+      "description": "Nivel de riesgo de las operaciones del agente"
+    },
+    "skillsInvocables": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Skills que este agente puede invocar. Valor especial 'todos' = wildcard (sin restriccion de skill); usar solo en agentes generalistas (investigador-swl, planificador-swl) cuando listar 162 skills es impractico. Para todos los demas agentes, listar skills especificos siguiendo privilegio minimo (regla seguridad-agentes.md)."
+    },
+    "skillsRestringidos": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Skills que este agente NO debe invocar"
+    },
+    "permisosRed": {
+      "type": "boolean",
+      "description": "Si el agente puede hacer llamadas de red"
+    },
+    "permisosEscritura": {
+      "type": "boolean",
+      "description": "Si el agente puede escribir archivos"
+    },
+    "permisosComandos": {
+      "type": "boolean",
+      "description": "Si el agente puede ejecutar comandos bash"
+    },
+    "presupuestoMaxUsd": {
+      "type": "number",
+      "minimum": 0.01,
+      "maximum": 50,
+      "description": "Presupuesto maximo en USD por invocacion del agente. Inspirado en maxBudgetUsd del Anthropic Agent SDK. El hook tracking-costos emite alerta al 80% y sugiere detener al 100%"
+    },
+    "maxTurnos": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "description": "Maximo de turnos (iteraciones de herramienta) por invocacion. Previene loops infinitos. Inspirado en maxTurns del Anthropic Agent SDK"
+    },
+    "toolBudget": {
+      "type": "object",
+      "properties": {
+        "simple": {
+          "type": "integer",
+          "description": "Tool calls para tareas simples"
+        },
+        "standard": {
+          "type": "integer",
+          "description": "Tool calls para tareas estandar"
+        },
+        "complex": {
+          "type": "integer",
+          "description": "Tool calls para tareas complejas"
+        }
+      },
+      "description": "Presupuesto de tool calls por nivel de complejidad"
+    },
+    "evolvable": {
+      "type": "boolean",
+      "description": "Marca AGP learnability. Si false, el loop de auto-evolucion NO debe proponer cambios a este agente. Default implicito (ausencia del campo): true para BAJO, false para MEDIO/ALTO."
+    },
+    "evolvable_scope": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "description",
+          "examples",
+          "instructions",
+          "skillsInvocables",
+          "skillsRestringidos",
+          "tools",
+          "model",
+          "nivelRiesgo",
+          "permisosRed",
+          "permisosEscritura",
+          "permisosComandos"
+        ]
+      },
+      "description": "Si evolvable=true, limita las secciones/campos que el loop puede modificar. Ausente implica 'description' y 'examples' unicamente — campos de seguridad NUNCA evolucionan sin aprobacion humana."
+    },
+    "invariantes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "campo",
+          "operador",
+          "valor"
+        ],
+        "properties": {
+          "campo": {
+            "type": "string",
+            "description": "Nombre de la propiedad del frontmatter a validar tras una evolucion (ej: 'permisosRed')."
+          },
+          "operador": {
+            "type": "string",
+            "enum": [
+              "eq",
+              "neq",
+              "lte",
+              "gte",
+              "in",
+              "not_in"
+            ],
+            "description": "Operador de comparacion. eq/neq: igualdad; lte/gte: orden numerico; in/not_in: pertenencia a lista."
+          },
+          "valor": {
+            "description": "Valor esperado. Para in/not_in debe ser array."
+          },
+          "razon": {
+            "type": "string",
+            "description": "Justificacion humana del invariante. Opcional pero recomendado."
+          }
+        },
+        "additionalProperties": false
+      },
+      "description": "Safety invariants que el commit gate (run-skill-evals.js) debe verificar tras cada evolucion."
+    },
+    "exclusiones": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Situaciones donde este agente NO debe invocarse aunque parezca relevante superficialmente. Campo propio de swl-ses; previene activacion tangencial (agent hijacking) por similitud de terminos en description. Equivalente estructural de la seccion 'Cuando NO invocarme' en el cuerpo, legible por herramientas de analisis sin parsear markdown. Aditivo, no breaking, aplicable a agentes con evolvable:false (metadata defensiva, no evolucion AGP — ver ADR-0004)."
+    },
+    "fase": {
+      "type": "string",
+      "enum": [
+        "discover",
+        "plan",
+        "implement",
+        "verify",
+        "release",
+        "learn",
+        "meta",
+        "cross"
+      ],
+      "description": "Fase del SDLC en que opera el agente. Vocabulario controlado para routing deterministico del orquestador sin parsear description. discover=research/UX/discovery; plan=arquitectura/planificacion; implement=codigo/implementacion; verify=revision/testing/seguridad; release=deploy/release; learn=auto-evolucion/aprendizaje; meta=componentes del sistema SWL mismo; cross=transversal a varias fases. Aditivo, opcional. Inspirado en patron Phase de Bug-Bounty-Agents/AGENTS.md y patron Workflow-vs-Agent del articulo Anthropic 'Building Effective AI Agents'."
+    },
+    "dominio": {
+      "type": "string",
+      "enum": [
+        "backend",
+        "frontend",
+        "mobile",
+        "data",
+        "infra",
+        "security",
+        "ux",
+        "quality",
+        "docs",
+        "process",
+        "meta",
+        "general"
+      ],
+      "description": "Dominio tecnico primario del agente. Vocabulario controlado para filtrado y matching. backend=APIs/servidores; frontend=UI/web; mobile=Android/iOS/cross; data=BD/ETL/datos; infra=cloud/CI/devops; security=auditoria/OWASP; ux=diseno/usabilidad; quality=tests/QA/code review; docs=documentacion; process=workflow/orquestacion; meta=sistema SWL; general=transversal. Aditivo, opcional."
+    },
+    "fragmentos": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^_[a-z][a-z0-9-]*$"
+      },
+      "description": "Lista de bloques de prompt compartidos no-routables (archivos agentes/_*.md) que este agente importa literalmente en su system prompt. Permite centralizar texto repetido entre multiples agentes sin duplicacion. Los fragmentos NO son skills (no se invocan dinamicamente) ni agentes (no son routables por el orquestador). Convencion: prefijo _ en kebab-case, sin sufijo -swl. Ejemplo: ['_brevedad-output-ref', '_hitl-alto-riesgo']. Inspirado en patron _scope-guard.md de Bug-Bounty-Agents."
+    },
+    "strategy": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Intent Engineering Parte 1 (Pawel Huryn, Lead Agents Like Humans). Lineas que enmarcan las decisiones del agente: vision, mercado/proyecto donde opera, tradeoffs preferidos. Heredable del CLAUDE.md del proyecto pero declarable por agente cuando el rol lo requiera. Opcional, aditivo. Obligatorio para agentes nivelRiesgo:ALTO segun reglas/intent-engineering.md."
+    },
+    "healthMetrics": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Intent Engineering Parte 4 (Pawel Huryn). Lo que NO debe degradar mientras el agente persigue su objetivo (Goodhart's Law: cuando una medida se vuelve target, deja de ser una buena medida). Lista de invariantes blandas que el agente debe proteger. Distinto de invariantes hard (que viven en hooks/validadores). Opcional, aditivo. Obligatorio para agentes nivelRiesgo:ALTO."
+    },
+    "steering": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Intent Engineering Parte 6 (Pawel Huryn) - prompt-level constraints. Guias de comportamiento, riesgo preferido, tono. Influyen el razonamiento del agente pero NO lo obligan (sin enforcement). El modelo puede desviarse documentando por que. Distinto de hardGuardrails (orchestration-level). Acepta texto inline o referencia a regla global con sintaxis '@reglas/X.md'. Opcional, aditivo."
+    },
+    "hardGuardrails": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Intent Engineering Parte 6 (Pawel Huryn) - orchestration-level constraints. Restricciones aplicadas por hooks, schemas, permisos, sandbox. NO admiten desviacion bajo ninguna circunstancia. Si una hard guardrail bloquea una tarea legitima, el agente escala (no la rodea). Acepta texto inline o referencia a regla/hook con sintaxis '@reglas/X.md' o '@hooks/Y.js'. Opcional, aditivo. Obligatorio para agentes nivelRiesgo:ALTO."
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/agent-message.schema.json

@@ -1,53 +1,73 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://swl-ses.dev/schemas/agent-message.json",
-  "title": "SWL Agent Message",
-  "description": "Schema de validacion para mensajes entre agentes SWL",
-  "type": "object",
-  "required": ["id", "type", "from", "to", "timestamp", "status"],
-  "properties": {
-    "id": {
-      "type": "string",
-      "pattern": "^msg-[a-z0-9]+-[a-z0-9]+$",
-      "description": "Identificador unico del mensaje generado por generarMessageId()"
-    },
-    "type": {
-      "type": "string",
-      "enum": ["task_handoff", "query", "response", "completed", "conflict"],
-      "description": "Tipo de mensaje segun el protocolo SWL inter-agent"
-    },
-    "from": {
-      "type": "string",
-      "description": "Nombre del agente emisor"
-    },
-    "to": {
-      "type": "string",
-      "description": "Nombre del agente destinatario o 'broadcast' para todos"
-    },
-    "payload": {
-      "type": "object",
-      "description": "Datos del mensaje, estructura libre segun type"
-    },
-    "contextFiles": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Rutas de archivos relevantes al mensaje, usadas para deteccion de conflictos"
-    },
-    "timestamp": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Fecha y hora de creacion del mensaje en formato ISO 8601"
-    },
-    "status": {
-      "type": "string",
-      "enum": ["pending", "processed", "expired"],
-      "description": "Estado actual del mensaje en el ciclo de vida del protocolo"
-    },
-    "processedAt": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Fecha y hora en que el mensaje fue marcado como procesado"
-    }
-  },
-  "additionalProperties": false
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://swl-ses.dev/schemas/agent-message.json",
+  "$schemaVersion": "1.0.0",
+  "title": "SWL Agent Message",
+  "description": "Schema de validacion para mensajes entre agentes SWL",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "from",
+    "to",
+    "timestamp",
+    "status"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^msg-[a-z0-9]+-[a-z0-9]+$",
+      "description": "Identificador unico del mensaje generado por generarMessageId()"
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "task_handoff",
+        "query",
+        "response",
+        "completed",
+        "conflict"
+      ],
+      "description": "Tipo de mensaje segun el protocolo SWL inter-agent"
+    },
+    "from": {
+      "type": "string",
+      "description": "Nombre del agente emisor"
+    },
+    "to": {
+      "type": "string",
+      "description": "Nombre del agente destinatario o 'broadcast' para todos"
+    },
+    "payload": {
+      "type": "object",
+      "description": "Datos del mensaje, estructura libre segun type"
+    },
+    "contextFiles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Rutas de archivos relevantes al mensaje, usadas para deteccion de conflictos"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Fecha y hora de creacion del mensaje en formato ISO 8601"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "pending",
+        "processed",
+        "expired"
+      ],
+      "description": "Estado actual del mensaje en el ciclo de vida del protocolo"
+    },
+    "processedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Fecha y hora en que el mensaje fue marcado como procesado"
+    }
+  },
+  "additionalProperties": false
+}