@saulwade/swl-ses 1.0.0

package/habilidades/api-rest-diseno/recursos/referencia-api.md

@@ -0,0 +1,140 @@
+# API REST — Referencia completa
+
+## Paginación por cursor (recomendada para datos en tiempo real)
+
+```
+GET /facturas?cursor=eyJpZCI6IjEyMyIsImZlY2hhIjoiMjAyNiJ9&limit=20
+
+# Respuesta
+{
+  "items": [...],
+  "pagination": {
+    "cursor_siguiente": "eyJpZCI6IjE0MyIsImZlY2hhIjoiMjAyNiJ9",
+    "cursor_anterior": "eyJpZCI6IjEwMyIsImZlY2hhIjoiMjAyNiJ9",
+    "tiene_siguiente": true,
+    "tiene_anterior": true,
+    "total": 847
+  }
+}
+```
+
+## Paginación por offset (simple, pero inestable con inserciones)
+
+```
+GET /facturas?page=3&page_size=20
+
+# Respuesta
+{
+  "items": [...],
+  "pagination": {
+    "page": 3,
+    "page_size": 20,
+    "total": 847,
+    "total_paginas": 43,
+    "tiene_siguiente": true,
+    "tiene_anterior": true
+  }
+}
+```
+
+**Elegir cursor cuando**: los datos se actualizan frecuentemente, la consistencia entre
+páginas importa, o la colección es grande (>10k elementos).
+
+---
+
+## Filtrado y ordenamiento completo
+
+### Query parameters para filtros
+
+```
+# Filtros simples
+GET /facturas?estatus=emitida&fecha_desde=2026-01-01&fecha_hasta=2026-03-31
+
+# Filtro de texto (búsqueda)
+GET /facturas?q=empresa+acme
+
+# Filtros múltiples del mismo campo
+GET /facturas?estatus=emitida&estatus=pendiente
+
+# Ordenamiento: prefijo - para descendente
+GET /facturas?orden=-fecha,folio
+
+# Proyección de campos
+GET /facturas?campos=id,folio,monto_total
+```
+
+### Convenciones de filtros de fecha
+
+```
+fecha_desde / fecha_hasta    # rango de fecha
+creado_desde / creado_hasta  # rango de creación
+```
+
+---
+
+## HATEOAS — Hypermedia
+
+Incluir links a recursos relacionados en las respuestas:
+
+```json
+{
+  "id": "factura-123",
+  "folio": "F-00001",
+  "estatus": "emitida",
+  "monto_total": 1160.00,
+  "_links": {
+    "self": { "href": "/v1/facturas/factura-123" },
+    "cancelar": { "href": "/v1/facturas/factura-123/cancelar", "method": "POST" },
+    "items": { "href": "/v1/facturas/factura-123/items" },
+    "cliente": { "href": "/v1/clientes/cliente-456" }
+  }
+}
+```
+
+En APIs internas, HATEOAS es opcional. En APIs públicas mejora la descubribilidad.
+
+---
+
+## Headers importantes
+
+```
+# Respuesta con recurso creado
+Location: /v1/facturas/factura-123
+
+# Caché
+Cache-Control: max-age=3600, must-revalidate
+ETag: "33a64df551425fcc55e4d42a148795d9f25f89d"
+
+# Rate limiting
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 847
+X-RateLimit-Reset: 1711324800
+
+# Idempotencia en POST (para operaciones que deben ser idempotentes)
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+```
+
+---
+
+## Versionado — detalles
+
+### Versionado en la URI (recomendado para APIs públicas)
+
+```
+https://api.empresa.com/v1/facturas
+https://api.empresa.com/v2/facturas
+```
+
+### Versionado en header (más limpio, más difícil de probar)
+
+```
+GET /facturas
+Accept: application/vnd.empresa.v2+json
+```
+
+### Estrategia de deprecación
+
+1. Anunciar con al menos 6 meses de anticipación.
+2. Agregar header `Deprecation: date="2027-01-01"` a respuestas de versiones deprecadas.
+3. Agregar header `Sunset: Mon, 01 Jan 2027 00:00:00 GMT`.
+4. Mantener compatibilidad hasta la fecha de sunset.

package/habilidades/aprendizaje-continuo/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: aprendizaje-continuo
+description: >
+  Sistema de aprendizaje continuo v2.1 basado en instintos. Cubre observacion de
+  sesion via hooks, creacion y gestion de instintos con niveles de confianza,
+  tres scopes (proyecto/dominio/global), degradacion automatica por contradiccion,
+  promocion a skills/comandos/agentes, evolucion (merge, split, deprecate) y
+  proteccion contra contaminacion cross-proyecto.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para consultar instintos ya cargados en la sesión actual — si el perfil fue leído, re-cargarlo es desperdicio de contexto."
+  - "No cargar para registrar una decisión de proyecto; las decisiones de diseño van a `DECISIONS.md` o APRENDIZAJES.md, no al sistema de instintos."
+  - "No cargar para gestionar la memoria nativa de Claude Code (auto-memory); este skill cubre instintos de `instintos/*.yaml`, canal distinto."
+  - "No cargar para promover un draft a instinto global sin evidence_count ≥ 3 — la promoción prematura contamina el scope global con datos sin confirmar."
+evolvable: true  # default para skill estandar
+---
+# Aprendizaje Continuo v2 — Sistema de Instintos
+
+## Concepto Central
+
+Un **instinto** es una unidad de conocimiento aprendido de la experiencia real de sesión.
+A diferencia de las skills (conocimiento declarativo estático), los instintos son
+conocimiento inductivo: emergen de observar patrones repetidos en el comportamiento
+del agente y los resultados que produce.
+
+El sistema tiene cuatro capas:
+
+```
+Observación → Instinto (draft) → Instinto (consolidado) → Promoción
+   (hook)       confianza<0.5      confianza≥0.5         skill/cmd/agente
+```
+
+---
+
+## 1. Observación via Hooks
+
+### Cobertura del 100% de actividad de sesión
+
+Todo lo que el agente hace pasa por hooks instrumentados:
+
+```jsonc
+// .claude/settings.json — hooks de observación
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [{ "type": "command", "command": "node hooks/observe-pre.js" }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [{ "type": "command", "command": "node hooks/observe-post.js" }]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [{ "type": "command", "command": "node hooks/session-end.js" }]
+      }
+    ]
+  }
+}
+```
+
+### Qué observar en cada evento
+
+| Evento | Datos relevantes | Señal de instinto |
+|--------|-----------------|-------------------|
+| PreToolUse | tool_name, input | Herramienta usada antes de X |
+| PostToolUse | tool_name, output, duration_ms | Herramienta exitosa/fallida |
+| Stop | session_id, turn_count | Patrón de sesión completa |
+
+**Regla**: los hooks de observación NUNCA deben producir exit code != 0.
+Un fallo de observación no debe interrumpir el trabajo del agente.
+
+---
+
+## 2. Niveles de Confianza
+
+### Escala de confianza (0.0 — 1.0)
+
+| Rango | Estado | Significado |
+|-------|--------|-------------|
+| 0.0 – 0.29 | draft | Observado 1-2 veces, no fiable |
+| 0.30 – 0.49 | draft | Patrón emergente, necesita confirmación |
+| 0.50 – 0.69 | activo | Confiable para el scope actual |
+| 0.70 – 0.89 | activo | Alta confianza, considerar promoción |
+| 0.90 – 1.00 | activo | Candidato inmediato a skill/comando |
+
+### Algoritmo de actualización de confianza
+
+```
+nueva_confianza = confianza_actual + (0.1 × peso_evento)
+
+peso_evento:
+  confirmacion_exitosa    = +1.0
+  confirmacion_prevencion = +0.8
+  excepcion_encontrada    = -0.3
+  refutacion_directa      = -0.5
+```
+
+La confianza nunca supera 0.95 automáticamente — el último 5% requiere
+revisión humana explícita antes de promoción.
+
+---
+
+## 3. Scope: Proyecto, Dominio y Global
+
+### Scope de proyecto
+
+- El instinto aplica solo en el directorio del proyecto actual
+- Se almacena en `.claude/instintos/`
+- Se activa cuando `PROJECT_NAME` coincide
+- Ejemplo: "En este proyecto, los modelos usan prefijo `tb_`"
+
+### Scope de dominio (nuevo en v4.1)
+
+- El instinto aplica a todos los proyectos que usan el mismo stack/dominio
+- Se almacena en `~/.claude/instintos/dominio/`
+- Se activa cuando el proyecto actual coincide con las condiciones de activación
+- Ejemplo: "En FastAPI, los background tasks no tienen acceso a la session de BD del request"
+
+### Scope global
+
+- El instinto aplica en cualquier proyecto
+- Se almacena en `~/.claude/instintos/`
+- Se activa siempre
+- Ejemplo: "Nunca usar `except: pass` en Python"
+
+Para referencia completa de dominios válidos, reglas de promoción de scope, formato de instinto,
+evolución (merge/split/deprecate), protección cross-proyecto y estructura de directorio,
+ver [recursos/referencia-instintos.md](recursos/referencia-instintos.md).
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Instinto de scope global demasiado específico de un framework**: un instinto como "En FastAPI siempre usar `selectinload`" se promueve a `global.yaml` porque tuvo alta confianza. Causa: el criterio de promoción no verificó que el patrón sea cross-proyecto y no de dominio. Solución: antes de mover a global, aplicar el filtro "¿le sirve esto a un ingeniero en cualquier stack?"; si no, mantenerlo en `dominio.yaml` o `proyecto.yaml`.
+- **Hooks de observación con exit code != 0 interrumpen la sesión**: el hook `observe-pre.js` lanza una excepción y Claude Code detiene la tarea en curso. Causa: violación de la regla "los hooks de observación NUNCA deben producir exit code != 0". Solución: envolver toda la lógica del hook en `try/catch` y loggear el error al stderr sin propagarlo — la observabilidad nunca debe bloquear el trabajo productivo.
+- **Duplicación de instintos entre `proyecto.yaml` y `APRENDIZAJES.md`**: el mismo anti-patrón existe en ambos canales con información inconsistente. Causa: el instinto se creó manualmente sin verificar si ya había una entrada en APRENDIZAJES.md. Solución: antes de crear un instinto nuevo, ejecutar `memoria-busqueda` para verificar si ya existe en otro canal; si existe, actualizar el canal correcto según `reglas/memoria-consolidada.md`.
+- **Confianza llegando a 0.95 sin revisión humana**: el algoritmo suma 0.1 por evento y el instinto llega a 0.95 sin que nadie lo revise antes de la promoción. Causa: no se aplicó la restricción del último 5% (requiere revisión explícita). Solución: al llegar a 0.90, el sistema debe emitir un checkpoint `human-verify` antes de superar ese umbral — automatizar la vigilancia en `session-end.js`.
+
+## Anti-patrones
+
+- Crear instintos sin evidencia (mínimo 2 observaciones para pasar de draft)
+- Instintos con scope global demasiado específicos a un framework de nicho
+- No actualizar la confianza cuando el instinto previene un error (refuerzo positivo)
+- Fusionar instintos de dominios distintos sin justificación clara
+- Ignorar instintos en cuarentena — siempre revisarlos en la fecha programada

package/habilidades/aprendizaje-continuo/evals/evals.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "../../../schemas/skill-evals.schema.json",
+  "skill_name": "aprendizaje-continuo",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para aprendizaje-continuo — sistema de instintos, scopes, confianza, degradación.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Un patrón se observó 5 veces sin contradicciones. ¿A qué confianza debería subir el instinto?",
+      "files": [],
+      "expectations": [
+        "La respuesta indica confianza ≥ 0.8 (o sobre la tabla de promoción).",
+        "La respuesta menciona que se puede promover a skill/cmd/agente cuando confidence ≥ 0.8."
+      ],
+      "tags": ["promotion"]
+    },
+    {
+      "id": 1,
+      "prompt": "Un instinto con confidence 0.7 recibe una contradicción observada. ¿Qué le pasa?",
+      "files": [],
+      "expectations": [
+        "La respuesta indica que se degrada (reduce confidence).",
+        "La respuesta menciona el hook `degradacion-instintos.js` como el mecanismo.",
+        "La respuesta describe que con ≥3 contradicciones se marca `[DEGRADADO]`."
+      ],
+      "tags": ["degradation"]
+    },
+    {
+      "id": "scopes",
+      "prompt": "¿Cuáles son los tres scopes de instintos y cuándo se promueve un instinto de project a global?",
+      "files": [],
+      "expectations": [
+        "Los tres scopes son: project, domain, global.",
+        "Promoción a global requiere confidence > 0.8.",
+        "La respuesta menciona protección anti-contaminación cross-proyecto."
+      ],
+      "tags": ["scopes"]
+    },
+    {
+      "id": "anti-pattern-direct-skill-creation",
+      "prompt": "Observo un patrón útil en una sesión. ¿Debo crear un skill inmediatamente?",
+      "files": [],
+      "expectations": [
+        "La respuesta indica que NO inmediatamente.",
+        "La respuesta menciona la escalera: solución ad-hoc → repetible → skill.",
+        "La respuesta describe que se requieren ≥3 ocurrencias exitosas antes de promover a skill."
+      ],
+      "grading_guidance": "Failure si sugiere crear skill desde primer observación.",
+      "tags": ["anti-pattern"]
+    }
+  ]
+}

package/habilidades/aprendizaje-continuo/recursos/referencia-instintos.md

@@ -0,0 +1,290 @@
+# Referencia Completa — Sistema de Instintos
+
+## Hook de Observación Mínimo (Node.js)
+
+```javascript
+// hooks/observe-post.js
+const fs = require('fs');
+
+const input = JSON.parse(fs.readFileSync('/dev/stdin', 'utf8'));
+const { tool_name, tool_input, tool_response } = input;
+
+const event = {
+  ts: Date.now(),
+  tool: tool_name,
+  success: !tool_response?.error,
+  duration_ms: tool_response?.duration_ms ?? null,
+  project: process.env.PROJECT_NAME ?? 'global',
+};
+
+// Append al log de observaciones
+const logPath = process.env.OBSERVATIONS_LOG ?? '.claude/observations.jsonl';
+fs.appendFileSync(logPath, JSON.stringify(event) + '\n');
+
+// Exit 0 obligatorio — nunca bloquear el flujo
+process.exit(0);
+```
+
+---
+
+## Formato Completo de un Instinto
+
+```yaml
+---
+id: instinto-20240315-001
+titulo: "Siempre usar selectinload en queries con relaciones"
+confianza: 0.75
+scope: proyecto              # "proyecto" | "global"
+proyecto: sigaf-backend      # solo si scope=proyecto
+observaciones: 7             # cuántas veces se observó
+primera_vez: "2024-03-10"
+ultima_vez: "2024-03-15"
+estado: activo               # "draft" | "activo" | "deprecado" | "promovido"
+promovido_a: null            # "skill:fastapi-experto" | "comando:fix-selectin" | null
+tags: [sqlalchemy, async, orm]
+---
+
+## Descripción
+
+Al usar SQLAlchemy async, cada vez que se accede a una relación en la
+serialización Pydantic sin `selectinload()` se produce `MissingGreenlet`.
+
+## Patrón observado
+
+En 7 sesiones de trabajo con el modelo `fastapi-experto`, se detectó que
+queries sin eager loading causaban errores en producción que no aparecían
+en tests síncronos.
+
+## Acción correctiva
+
+```python
+# SIEMPRE incluir selectinload para relaciones accedidas
+stmt = select(Modelo).options(selectinload(Modelo.relacion))
+```
+
+## Condiciones de activación
+
+- Proyecto usa SQLAlchemy async (detectado en requirements.txt)
+- Se están escribiendo endpoints FastAPI con Pydantic
+
+## Evidencia
+
+- Sesión 2024-03-10: error MissingGreenlet en endpoint /usuarios
+- Sesión 2024-03-12: mismo error en endpoint /proyectos
+- Sesión 2024-03-15: prevenido al aplicar selectinload preventivamente
+```
+
+---
+
+## Scope de Dominio (v4.1)
+
+Formato de instinto con scope dominio:
+
+```yaml
+---
+scope: dominio
+dominio: backend-python
+condiciones_activacion:
+  - "requirements.txt contiene fastapi"
+  - "pyproject.toml contiene fastapi"
+---
+```
+
+Dominios válidos (alineados con la tabla de habilidades del sistema):
+
+| Dominio | Se activa cuando el proyecto contiene |
+|---------|--------------------------------------|
+| `backend-python` | requirements.txt/pyproject.toml con fastapi, django, flask |
+| `backend-node` | package.json con express, fastify, nestjs |
+| `frontend-react` | package.json con react, next |
+| `frontend-angular` | package.json con @angular/core |
+| `frontend-css` | archivos *.css, *.scss, tailwind.config.* |
+| `mobile-android` | build.gradle con android, archivos *.kt |
+| `mobile-ios` | *.xcodeproj, Package.swift, archivos *.swift |
+| `mobile-cross` | package.json con react-native, pubspec.yaml con flutter |
+| `datos` | archivos *.sql, dbt_project.yml, alembic/ |
+| `infra` | archivos *.tf, docker-compose*, k8s/ |
+| `seguridad` | auth/, security/, middleware/ |
+
+---
+
+## Reglas de Promoción de Scope
+
+**Proyecto -> Dominio**: Un instinto de proyecto puede ascender a dominio si:
+1. Se observa en 2+ proyectos distintos del mismo dominio
+2. La confianza es >= 0.6 en ambos proyectos
+3. La condición de activación es detectable automáticamente (archivo de config)
+
+**Dominio -> Global**: Un instinto de dominio puede ascender a global si:
+1. Se observa en 3+ dominios distintos con el mismo patrón
+2. La confianza es >= 0.7 en todos los dominios
+3. No contradice ningún instinto global existente
+
+**Degradación**: Un instinto puede bajar de scope si es contradicho en un contexto
+donde debería aplicar.
+
+```bash
+# Comando para promover scope
+node scripts/instinto-promover-scope.js \
+  --id instinto-20240315-001 \
+  --de proyecto \
+  --a dominio \
+  --dominio backend-python
+```
+
+---
+
+## Promoción de Instintos
+
+### A Skill
+
+Cuando un instinto tiene confianza >= 0.85 y cubre un dominio técnico bien definido:
+
+```bash
+# Genera un borrador de SKILL.md a partir del instinto
+node scripts/instinto-a-skill.js \
+  --instinto .claude/instintos/instinto-20240315-001.md \
+  --skill-dir habilidades/selectinload-sqlalchemy/
+```
+
+El instinto se marca `estado: promovido` y `promovido_a: skill:selectinload-sqlalchemy`.
+
+### A Comando
+
+Cuando el instinto describe una acción repetitiva que puede automatizarse:
+
+```bash
+node scripts/instinto-a-comando.js \
+  --instinto .claude/instintos/instinto-20240318-003.md \
+  --comando-dir comandos/fix-missing-selectin/
+```
+
+### A Agente
+
+Cuando el instinto describe un workflow completo y recurrente (confianza >= 0.90):
+
+```bash
+node scripts/instinto-a-agente.js \
+  --instinto .claude/instintos/instinto-20240320-007.md \
+  --agente-dir agentes/revisor-sqlalchemy/
+```
+
+---
+
+## Evolución de Instintos
+
+### Merge (fusión)
+
+Dos instintos con patrones solapados se fusionan:
+
+```yaml
+# merge-plan.yaml
+fuente_a: instinto-20240310-001   # "usar selectinload"
+fuente_b: instinto-20240312-003   # "lazy='selectin' en relaciones Usuario"
+resultado: instinto-20240320-010  # "estrategia completa de eager loading async"
+razon: "Ambos instintos cubren el mismo dominio desde ángulos complementarios"
+```
+
+Regla: el instinto fusionado hereda `confianza = max(a, b) × 0.9` (penalty por fusión).
+
+### Split (división)
+
+Un instinto demasiado genérico se divide en instintos más específicos:
+
+```yaml
+# split-plan.yaml
+fuente: instinto-20240301-001   # "buenas prácticas SQLAlchemy"
+resultados:
+  - instinto-20240320-011       # "eager loading en queries async"
+  - instinto-20240320-012       # "session management en endpoints"
+  - instinto-20240320-013       # "commit solo en endpoint, nunca en service"
+razon: "El instinto original era demasiado amplio para activación precisa"
+```
+
+### Deprecate (deprecación)
+
+Un instinto se depreca cuando:
+- La librería cambió y el patrón ya no aplica
+- Se encontró una mejor práctica que lo reemplaza
+- La confianza cayó por debajo de 0.2 tras múltiples refutaciones
+
+```yaml
+estado: deprecado
+deprecado_en: "2024-04-01"
+razon: "SQLAlchemy 2.1 agregó lazy loading seguro en async por defecto"
+reemplazado_por: instinto-20240401-020
+```
+
+---
+
+## Protección contra Contaminación Cross-Proyecto
+
+### El problema
+
+Si los instintos de un proyecto contaminan otro proyecto, se generan
+sugerencias incorrectas. Ejemplo: el prefijo `tb_` de tablas de un proyecto
+legacy no debe aplicarse en un proyecto nuevo con convención `snake_case`.
+
+### Mecanismo de aislamiento
+
+```javascript
+// hooks/instinto-loader.js
+const projectName = process.env.PROJECT_NAME;
+const instintosGlobales = loadInstintos('~/.claude/instintos/');
+const instintosProyecto = loadInstintos(`.claude/instintos/`);
+
+// Los instintos de proyecto NUNCA se exportan a otros proyectos
+const instintosActivos = [
+  ...instintosGlobales.filter(i => i.scope === 'global'),
+  ...instintosProyecto.filter(i => i.proyecto === projectName),
+];
+```
+
+### Cuarentena de instintos sospechosos
+
+Cuando un instinto produce una sugerencia que el humano rechaza 3+ veces,
+entra en cuarentena automática:
+
+```yaml
+estado: cuarentena
+cuarentena_inicio: "2024-03-20"
+rechazos: 3
+cuarentena_fin: "2024-03-27"   # revisión en 7 días
+```
+
+Durante la cuarentena, el instinto no se activa pero tampoco se borra —
+se espera revisión humana.
+
+---
+
+## Directorio de Instintos
+
+Estructura recomendada en el proyecto:
+
+```
+.claude/
+└── instintos/
+    ├── index.yaml           # índice de todos los instintos activos
+    ├── draft/               # instintos con confianza < 0.5
+    ├── activos/             # instintos con confianza >= 0.5
+    ├── cuarentena/          # instintos rechazados en revisión
+    └── promovidos/          # instintos ya convertidos a skill/cmd/agente
+```
+
+### index.yaml mínimo
+
+```yaml
+version: 2
+ultimo_update: "2024-03-20"
+totales:
+  draft: 3
+  activos: 12
+  cuarentena: 1
+  promovidos: 5
+instintos:
+  - id: instinto-20240315-001
+    titulo: "Siempre usar selectinload en queries con relaciones"
+    confianza: 0.75
+    scope: proyecto
+    estado: activo
+```