@saulwade/swl-ses 1.6.0 → 1.6.3

package/habilidades/proceso-ddia-fundamentos/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: proceso-ddia-fundamentos
+description: >
+  Conceptos fundamentales del libro "Designing Data-Intensive Applications" de
+  Martin Kleppmann aplicables a sistemas no-distribuidos (como SWL): Cap 1
+  Reliability/Scalability/Maintainability como framework de evaluación, Cap 4
+  Schema Evolution con backward/forward compatibility, Cap 12 End-to-End
+  Argument y Trust-but-Verify. Cargar al diseñar manifiestos versionados,
+  evaluar arquitectura de un módulo, decidir dónde validar correctitud.
+when_to_use: >
+  Usar cuando el usuario menciona schema versioning, backward/forward compat,
+  end-to-end verification, trust but verify, reliability scalability
+  maintainability, RSM framework, Operability Simplicity Evolvability,
+  schema-evolution, evaluar arquitectura, decidir dónde validar.
+---
+
+# DDIA Fundamentos — RSM, Schema Evolution, End-to-End
+
+Adaptado de Martin Kleppmann, *"Designing Data-Intensive Applications"*
+(O'Reilly, 2017). Skill cubre los tres ejes del libro que aplican a SWL:
+
+- **Capítulo 1** — Reliability, Scalability, Maintainability como framework.
+- **Capítulo 4** — Schema Evolution (back/forward compatibility).
+- **Capítulo 12** — End-to-End Argument + Trust-but-Verify.
+
+Los demás capítulos del libro (2-3 data models / storage, 5-10 distributed
+systems) tratan dominios que SWL no es (no es BD, no es sistema distribuido).
+Se descartan por filtro de dominio (regla `arquitectura.md`).
+
+## Cuándo cargar
+
+- Diseñar un schema nuevo (manifest, frontmatter, JSON Schema) que
+  evolucionará en el tiempo.
+- Auditar un módulo SWL para evaluar Reliability/Scalability/Maintainability.
+- Decidir dónde poner una validación: en cada capa o solo end-to-end.
+- Resolver una duda sobre "¿esto se rompe si actualizo el sistema?" — es
+  pregunta de schema compatibility.
+
+## Cuándo NO cargar
+
+- Discusiones sobre replication, partitioning, consenso (Paxos/Raft) — esos
+  capítulos DDIA no aplican a SWL.
+- Streaming/event sourcing avanzado — cargar `Skill("proceso-ddia-streaming")`.
+- Optimización puntual de query SQL — cargar `Skill("performance-baseline")`.
+
+---
+
+## Parte 1 — Reliability, Scalability, Maintainability (RSM)
+
+Cita textual del libro (DDIA p.18, línea 1411-1453):
+
+> "It is well known that the majority of the cost of software is not in its
+> initial development, but in its ongoing maintenance — fixing bugs, keeping
+> its systems operational, investigating failures, adapting it to new
+> platforms, modifying it for new use cases, repaying technical debt, and
+> adding new features."
+
+### Las 3 dimensiones del RSM
+
+**Reliability** — el sistema sigue funcionando correctamente bajo:
+- Hardware faults
+- Software errors
+- Human errors
+
+Tipos de respuesta:
+- **Fault-tolerant**: el sistema absorbe la falla sin propagarla.
+- **Resilient**: degrada con gracia, no en cascada.
+
+**Aplicación a SWL**: hooks bloqueantes (`calidad-pre-commit`,
+`escaneo-secretos`) son fault-tolerance. Las escrituras atómicas
+(`hooks/lib/atomic-write.js`) son resilience contra crashes durante write.
+
+**Scalability** — cómo cambia el rendimiento cuando crece la carga:
+- Describir **carga** (parámetros: throughput, concurrent users, etc.)
+- Describir **rendimiento** (latencia: p50, p95, p99)
+
+**Aplicación a SWL**: las métricas `Skill("performance-baseline")` siguen
+este modelo. Carga = sesiones concurrentes, archivos por proyecto, agentes
+en cadena. Rendimiento = latencia de hooks, tiempo de respuesta de
+validadores.
+
+**Maintainability** — tres principios de diseño del libro:
+
+> "Operability: Make it easy for operations teams to keep the system running
+> smoothly.
+> Simplicity: Make it easy for new engineers to understand the system, by
+> removing as much complexity as possible from the system. (Note this is
+> not the same as simplicity of the user interface.)
+> Evolvability: Make it easy for engineers to make changes to the system in
+> the future, adapting it for unanticipated use cases as requirements
+> change. Also known as extensibility, modifiability, or plasticity."
+> (DDIA p.18-19, líneas 1435-1449)
+
+**Aplicación a SWL**:
+
+| Principio DDIA | Implementación SWL |
+|---|---|
+| Operability | `/swl:salud`, `/swl:dashboard`, `/swl:doctor`, runbooks |
+| Simplicity | Skills ≤300 líneas, módulos profundos (Ousterhout), zero-deps en `hooks/lib/` |
+| Evolvability | ADRs versionados, schemas opcionales aditivos, fragments compartidos |
+
+### Cómo usar RSM como rúbrica de evaluación
+
+Antes de declarar un módulo "listo", pregúntate:
+
+1. **Reliability**: ¿qué pasa si una entrada inesperada llega? ¿Si un hook
+   externo falla? ¿Si el filesystem se llena?
+2. **Scalability**: ¿el módulo escala con el tamaño del proyecto del
+   usuario? Si tiene 1000 archivos vs 10, ¿degrada linealmente o se
+   cuadratiza?
+3. **Maintainability** (los 3 sub-principios):
+   - ¿Un operario nuevo puede operarlo sin leer todo el código?
+   - ¿Un ingeniero nuevo puede entenderlo sin un curso?
+   - ¿Un cambio de requisito se acomoda sin reescribir?
+
+Si la respuesta es "no" a más de uno, el módulo necesita refactor antes de
+release.
+
+---
+
+## Parte 2 — Schema Evolution (Cap 4)
+
+Cita textual del libro (DDIA p.112, línea 5706-5719):
+
+> "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.
+>
+> Backward compatibility is normally not hard to achieve: as author of the
+> newer code, you know the format of data written by older code, and so
+> you can explicitly handle it (if necessary by simply keeping the old code
+> to read the old data). Forward compatibility can be trickier, because it
+> requires older code to ignore additions made by a newer version of the
+> code."
+
+### Las 2 direcciones de compatibilidad
+
+Cuando un schema evoluciona, hay dos preguntas distintas:
+
+| Pregunta | Tipo | Difficulty |
+|---|---|---|
+| ¿Código nuevo lee datos viejos? | Backward | Fácil |
+| ¿Código viejo lee datos nuevos? | Forward | Más difícil |
+
+**Backward compat es fácil**: el código nuevo conoce ambas versiones del
+schema, puede manejar los dos formatos.
+
+**Forward compat es difícil**: el código viejo NO sabe que existe el campo
+nuevo. Para que funcione, el código viejo debe **ignorar campos
+desconocidos** sin romperse.
+
+### Aplicación a schemas SWL
+
+SWL tiene 14 archivos `schemas/*.schema.json`. Reglas operativas:
+
+1. **Campos nuevos siempre opcionales**: agregar `myField: { type: "..." }`
+   sin marcarlo `required`. Código viejo lo ignora (forward-compat OK).
+   Código nuevo lo usa si está presente (backward-compat OK).
+
+2. **NUNCA renombrar campos en MINOR/PATCH**: rename = breaking. Si hay
+   que renombrar, mantener ambos durante 1 release (deprecación) y
+   eliminar en el MAJOR siguiente.
+
+3. **NUNCA cambiar tipo de un campo en MINOR/PATCH**: cambiar `string` →
+   `array` rompe ambas direcciones. Es MAJOR.
+
+4. **Agregar enum value es compatible**: si `nivelRiesgo` acepta
+   `[BAJO, MEDIO, ALTO]`, agregar `CRÍTICO` es backward-compat (código
+   nuevo lo entiende, código viejo lo rechaza pero no se rompe).
+
+5. **Eliminar enum value es breaking**: código nuevo rechaza algo que
+   código viejo escribía.
+
+### Detección de breaking changes
+
+Helper `scripts/lib/schema-version.js` (creado en F4) implementa estas
+reglas. Uso esperado:
+
+```js
+const { verificarCompatibilidad } = require('./scripts/lib/schema-version');
+const r = verificarCompatibilidad(documento, schema);
+// r = { compatible: bool, modo: "backward"|"forward"|"none", advertencias }
+```
+
+Tres modos según versiones:
+- Doc 1.0.0 + Schema 1.0.0 → `modo: "none"` (idénticas).
+- Doc 1.0.0 + Schema 1.1.0 → `modo: "forward"` (dato viejo, código nuevo).
+- Doc 1.1.0 + Schema 1.0.0 → `modo: "backward"` (dato nuevo, código viejo).
+- Doc 2.0.0 + Schema 1.0.0 → `compatible: false` (MAJOR rompe).
+
+---
+
+## Parte 3 — End-to-End Argument (Cap 12)
+
+Concepto del libro: la verificación de correctitud debe vivir en la
+frontera del sistema (end-to-end), no en cada capa intermedia.
+
+> "The End-to-End Argument for Databases" (DDIA p.516, sección referenciada)
+
+### El principio aplicado
+
+Si validas en cada capa intermedia:
+- Capa 1: valida → pasa
+- Capa 2: valida → pasa
+- Capa 3: valida → pasa
+- Resultado: dato corrupto entregado al usuario porque ninguna capa
+  verificó la **invariante de negocio** completa.
+
+Si validas end-to-end:
+- Capa 1, 2, 3: hacen su trabajo sin validar
+- Frontera del sistema: verifica la invariante completa
+- Resultado: si falla, se detecta antes de entregar al usuario.
+
+### Aplicación a SWL
+
+- `/swl:verificar` con goal-backward 4 niveles es end-to-end.
+- Hooks de validación intermedios (`calidad-pre-commit`,
+  `escaneo-secretos`) son fault-tolerance, no end-to-end. Detectan
+  problemas obvios temprano para reducir blast radius — no reemplazan la
+  verificación end-to-end.
+- Las dos capas son complementarias: hooks rápidos en cada step, verifier
+  end-to-end al cierre de fase.
+
+### Trust-but-Verify (Cap 12, p.528)
+
+El sistema debe **confiar provisionalmente** en sus componentes
+(hooks pasan → asumimos correcto) pero **verificar** la invariante final
+con evidencia, no con auto-reporte de los componentes.
+
+Aplicación SWL: regla `verificar-citas-normativas.md` aplica este
+principio a citas archivo:línea — un sub-agente reportó "está
+implementado en X:42"; el padre verifica con `Read`+`grep` antes de
+aceptar.
+
+---
+
+## Resumen — qué se llevó SWL del libro
+
+| Concepto DDIA | Dónde vive en SWL |
+|---|---|
+| Reliability/Scalability/Maintainability como framework | Este skill como rúbrica de evaluación |
+| Operability / Simplicity / Evolvability | Skills ≤300 líneas + observabilidad-swl + ADRs |
+| Backward / Forward compat | `$schemaVersion` + `scripts/lib/schema-version.js` (F4) |
+| End-to-End Argument | `/swl:verificar` goal-backward |
+| Trust-but-Verify | regla `verificar-citas-normativas.md` |
+
+## Origen
+
+Skill creado el 2026-05-18 como parte de Opción B de integración
+`temp/Designing Data Intensive Applications by Martin Kleppmann.md`. Ver
+ADR-0025 para la decisión de scope. Skill hermano:
+`proceso-ddia-streaming` (Cap 11 event sourcing aplicado a
+`evolucion/*.jsonl`).

package/habilidades/proceso-ddia-streaming/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: proceso-ddia-streaming
+description: >
+  Patrones de Stream Processing del libro DDIA (Cap 11, Martin Kleppmann)
+  aplicados a archivos JSONL append-only de SWL: event sourcing, idempotencia,
+  exactly-once vs at-least-once, replay desde offset. Cargar al diseñar hooks
+  que persistan eventos, modificar evolucion/*.jsonl, audit-trail.jsonl o
+  nudges.jsonl, o cuando un consumidor de JSONL deba ser idempotente.
+when_to_use: >
+  Usar cuando el usuario menciona JSONL append-only, event sourcing, audit
+  trail, idempotencia, exactly-once, replay, offset, consumidor de stream,
+  evolucion/, nudges, telemetria, hooks que escriben eventos.
+---
+
+# DDIA Streaming — event sourcing aplicado a JSONL de SWL
+
+Adaptado de Martin Kleppmann, *"Designing Data-Intensive Applications"*
+Capítulo 11 — Stream Processing. SWL no tiene Kafka ni stream processor
+real, pero opera con archivos JSONL append-only que se comportan como
+streams locales. Los patrones del Cap 11 aplican directamente.
+
+## Cuándo cargar
+
+- Crear un hook que persiste eventos en JSONL (telemetría, audit, evolución).
+- Diseñar un consumidor de `.planning/evolucion/*.jsonl`,
+  `.planning/audit.jsonl`, `.planning/comms/nudges.jsonl`.
+- Diagnosticar duplicación de eventos en JSONL.
+- Decidir si un hook debe ser idempotente o si basta con append.
+- Implementar replay de eventos desde un offset.
+
+## Cuándo NO cargar
+
+- Trabajo síncrono request/response sin event log → no aplica.
+- Sistema sin JSONL (sin streams locales) → cargar `proceso-ddia-fundamentos`.
+- Discusiones sobre Kafka/Flink/Spark reales → SWL no opera con esos.
+
+## Cita textual base (DDIA Cap 11, p.439-479)
+
+### Event Sourcing (p.457, línea 21753-21798)
+
+> "Event sourcing is a powerful technique for data modeling: from an
+> application point of view [...]"
+
+El libro distingue event sourcing de change data capture (CDC):
+- **CDC**: captura cambios de una base de datos relacional como stream.
+- **Event Sourcing**: la aplicación misma emite eventos como log primario;
+  el estado se deriva replicando los eventos.
+
+**SWL aplica event sourcing** (no CDC): no hay BD relacional intermedia.
+Los archivos JSONL son el log primario; cualquier proyección (instintos,
+métricas, dashboard) se deriva replicándolos.
+
+### Exactly-Once vs Effectively-Once (p.476, línea 22755)
+
+> "This principle is known as exactly-once semantics, although
+> effectively-once would be a more descriptive term."
+
+Distinción clave del libro:
+- **Exactly-once teórico**: el sistema garantiza que cada evento se
+  procesa una y solo una vez.
+- **Effectively-once práctico**: el evento puede llegar N veces, pero
+  el efecto visible es el de procesarlo 1 vez. Se logra con idempotencia.
+
+### Idempotencia (p.478, línea 22828-22845)
+
+> "An idempotent operation is one that you can perform multiple times,
+> and it has the same effect as if you performed it only once. For
+> example, setting a key in a key-value store to some fixed value is
+> idempotent (writing the value again simply overwrites the value with
+> an identical value), whereas incrementing a counter is not idempotent
+> (performing the increment again means the value is incremented twice)."
+
+Operación clave del libro: incluso operaciones no-idempotentes pueden
+hacerse idempotentes con metadata adicional (el offset del mensaje
+fuente).
+
+---
+
+## Aplicación a SWL — archivos JSONL del sistema
+
+| Archivo | Productor | Consumidores | ¿Es event source? |
+|---|---|---|---|
+| `.planning/evolucion/evoluciones.jsonl` | `/swl:evolucionar`, hook `evolucion-detector` | `/swl:evolucion-estado`, dashboard | Sí |
+| `.planning/evolucion/nudges.jsonl` | hooks varios | `/swl:salud`, `red-team-swl` | Sí |
+| `.planning/evolucion/agentes.jsonl` | hook `telemetria-agentes` | `/swl:metricas` | Sí |
+| `.planning/audit.jsonl` | hook `audit-trail` | auditorías, post-mortems | Sí (con Merkle) |
+| `.planning/comms/*.jsonl` | `notificador-swl` | inbox, gateway | Sí |
+
+Todos son **append-only logs** — escritura por `fs.appendFileSync` (regla
+CLAUDE.md). Nadie modifica ni borra entradas existentes.
+
+## Patrón 1 — Idempotencia con event ID
+
+**Problema**: un hook se ejecuta dos veces (re-trigger, retry) y emite el
+mismo evento. El consumidor lo procesa 2 veces, produciendo doble efecto.
+
+**Solución aplicada en SWL**: cada evento JSONL incluye un campo `id` único
+(UUID v4 o `timestamp + hash de payload`). El consumidor mantiene un
+set de IDs procesados (en `.planning/.processed-ids/`) y descarta
+duplicados.
+
+Ejemplo en hooks/lib (idiomático SWL):
+
+```js
+// Productor (hook)
+const crypto = require('crypto');
+const evento = {
+  id: crypto.randomUUID(),
+  ts: new Date().toISOString(),
+  type: 'agent.completed',
+  payload: { ... }
+};
+fs.appendFileSync(ruta, JSON.stringify(evento) + '\n');
+
+// Consumidor
+const procesados = cargarSetIds(); // del filesystem
+for (const linea of leerJSONL(ruta)) {
+  const e = JSON.parse(linea);
+  if (procesados.has(e.id)) continue; // idempotencia
+  aplicar(e);
+  procesados.add(e.id);
+  guardarSetIds(procesados);
+}
+```
+
+**Cuándo aplicar**: consumidores que ejecutan side-effects no-idempotentes
+(notificaciones, mutaciones de estado, incrementos de contador).
+
+**Cuándo NO aplicar**: consumidores que solo proyectan estado (instintos,
+métricas) — la idempotencia natural (re-procesar produce mismo estado)
+es suficiente.
+
+## Patrón 2 — Replay desde offset
+
+**Problema**: un consumidor crashea a mitad del JSONL. Al reiniciar,
+¿desde dónde continúa?
+
+**Solución aplicada en SWL**: persistir el byte-offset del último evento
+procesado en archivo separado (`.planning/.offsets/consumidor-X.offset`).
+Al iniciar, leer desde ese offset.
+
+```js
+const offsetFile = `.planning/.offsets/${consumidor}.offset`;
+const offset = fs.existsSync(offsetFile)
+  ? parseInt(fs.readFileSync(offsetFile, 'utf-8'), 10)
+  : 0;
+
+const fd = fs.openSync(ruta, 'r');
+// leer desde offset, procesar evento por evento
+// tras cada evento procesado: fs.writeFileSync(offsetFile, nuevoOffset)
+```
+
+**Garantía**: at-least-once. Si crashea entre procesar y guardar offset,
+el evento se reprocesa. Combinado con idempotencia (Patrón 1), se logra
+**effectively-once** (DDIA p.476).
+
+## Patrón 3 — Append-only sin borrado
+
+**Regla operacional SWL**: los archivos JSONL NUNCA se reescriben enteros
+ni se editan entradas pasadas. Compactación (eliminar duplicados, agrupar)
+se hace creando un archivo `.jsonl.compacted` separado, dejando el
+original como audit trail.
+
+**Por qué importa**: si un hook reescribiera `audit.jsonl` con un nuevo
+contenido (incluso con razón válida), perderíamos la garantía de
+inmutabilidad que `audit-trail.js` con Merkle hash depende. El audit
+trail roto deja de ser auditable.
+
+## Patrón 4 — Schema evolution en eventos JSONL
+
+Los eventos JSONL evolucionan: campos nuevos, payloads modificados. Los
+consumidores deben tolerar eventos viejos sin romperse.
+
+Aplicar las reglas de `Skill("proceso-ddia-fundamentos")` § Schema
+Evolution:
+- Campos nuevos siempre opcionales.
+- `schemaVersion: "1.0.0"` por evento opcional pero recomendado.
+- Consumidores ignoran campos desconocidos (forward-compat).
+
+## Patrón 5 — Backpressure (cuándo NO aplica a SWL)
+
+DDIA trata extensamente backpressure: cuando el productor escribe más
+rápido que el consumidor. **SWL NO sufre este problema** porque:
+- Volumen de eventos por sesión: ~10²-10³ líneas, no millones.
+- Consumidores son sincrónicos bajo demanda (`/swl:salud`, dashboard).
+- No hay productor continuo de alta frecuencia.
+
+NO implementar backpressure / rate-limiting en JSONL writers. Es
+sobre-ingeniería.
+
+## Anti-patrones específicos a evitar
+
+- **Compactar JSONL en mismo archivo**: rompe inmutabilidad. Crear
+  `.compacted` separado.
+- **Confiar en orden de líneas para totalidad**: dos hooks concurrentes
+  pueden escribir entrelazado. Usar IDs únicos + timestamps, NO orden.
+- **Indexar JSONL en disco como BD**: el archivo es secuencial por
+  diseño. Si necesitas índice, proyecta a otra estructura (instintos,
+  métricas agregadas).
+- **Bloquear el productor durante write**: `fs.appendFileSync` es atómico
+  para writes ≤4096 bytes en sistemas POSIX (no aplica Windows, donde
+  hay carrera de race). Para Windows usar `atomicAppend` de
+  `hooks/lib/atomic-write.js` cuando el evento supera 4KB.
+
+## Gotchas no obvios
+
+- **`fs.appendFileSync` no es atómico en Windows con escrituras grandes**:
+  Node usa `WriteFile` que no garantiza atomicity para >4KB. Si el
+  evento JSON serializado supera 4KB, usar buffer + `atomicAppend`.
+- **Lectura de JSONL con `fs.readFileSync` carga todo a memoria**: si
+  un archivo crece a 100MB+, usar `readline` con stream. Pero para
+  swl-ses (volumen bajo), `readFileSync` es aceptable.
+- **`JSON.parse` en línea malformada lanza**: envolver en try/catch +
+  log de línea problemática. NUNCA dejar que un evento corrupto rompa
+  todo el replay.
+
+## Resumen — del libro a SWL
+
+| Concepto DDIA Cap 11 | Aplicación SWL |
+|---|---|
+| Event sourcing | Todos los `.planning/*.jsonl` |
+| Exactly-once → effectively-once | Idempotencia + at-least-once delivery |
+| Idempotencia con offset | Patrón 1 de este skill |
+| Replay desde offset | Patrón 2 de este skill |
+| Append-only inmutable | Regla operacional SWL |
+| Backpressure | NO aplica (volumen bajo) |
+
+## Origen
+
+Skill creado el 2026-05-18 como parte de Opción B (ver ADR-0025). Skill
+hermano: `proceso-ddia-fundamentos` (Cap 1, 4, 12 del mismo libro).