@saulwade/swl-ses 1.0.0

package/reglas/lenguajes/swift/testing.md

@@ -0,0 +1,242 @@
+# Regla: Testing en Swift / iOS
+
+Esta regla es OBLIGATORIA para todo código Swift nuevo o modificado.
+La orientación a protocolos de Swift permite mocks sin frameworks de generación.
+Swift Testing (Swift 6) es el estándar para código nuevo.
+
+---
+
+## Stack de testing obligatorio
+
+| Herramienta | Propósito |
+|------------|----------|
+| XCTest | Framework base (compatible con todas las versiones) |
+| swift-testing | Framework moderno para código Swift 6+ |
+| swift-snapshot-testing | Tests de regresión visual para vistas |
+| XCUITest | Tests de UI end-to-end |
+| Xcode Coverage | Reporte de cobertura integrado en Xcode |
+
+```swift
+// Package.swift — dependencias de test
+.package(url: "https://github.com/pointfreeco/swift-snapshot-testing", from: "1.16.0"),
+.package(url: "https://github.com/apple/swift-testing", from: "0.10.0"),
+```
+
+---
+
+## swift-testing para código Swift 6 nuevo
+
+`swift-testing` usa macros (`@Test`, `@Suite`) y es más expresivo que XCTest.
+Para proyectos que soportan iOS 16 o anterior, usar XCTest.
+
+```swift
+import Testing
+
+// BIEN — swift-testing con macros
+@Suite("PedidoViewModel")
+struct PedidoViewModelTests {
+
+    @Test("Carga pedidos correctamente")
+    func cargarPedidosExitoso() async throws {
+        // Given
+        let repositorioMock = MockPedidoRepository(pedidos: [.ejemplo])
+        let viewModel = PedidoViewModel(repositorio: repositorioMock)
+
+        // When
+        await viewModel.cargar()
+
+        // Then
+        #expect(viewModel.pedidos.count == 1)
+        #expect(!viewModel.isLoading)
+    }
+
+    @Test("Maneja error de red")
+    func cargarPedidosConError() async throws {
+        // Given
+        let repositorioMock = MockPedidoRepository(error: URLError(.notConnectedToInternet))
+        let viewModel = PedidoViewModel(repositorio: repositorioMock)
+
+        // When
+        await viewModel.cargar()
+
+        // Then
+        #expect(viewModel.error != nil)
+        #expect(viewModel.pedidos.isEmpty)
+    }
+}
+```
+
+---
+
+## Mocks basados en protocolos (sin frameworks de generación)
+
+La orientación a protocolos de Swift hace innecesarios los frameworks de mocking.
+Implementar mocks manualmente: son simples, legibles y sin dependencias.
+
+```swift
+// Protocolo de produccion
+protocol PedidoRepository {
+    func obtenerTodos() async throws -> [Pedido]
+    func guardar(_ pedido: Pedido) async throws
+}
+
+// Mock manual — simple y declarativo
+final class MockPedidoRepository: PedidoRepository {
+    var pedidos: [Pedido] = []
+    var errorALanzar: Error?
+    private(set) var guardarLlamado = false
+    private(set) var pedidoGuardado: Pedido?
+
+    func obtenerTodos() async throws -> [Pedido] {
+        if let error = errorALanzar { throw error }
+        return pedidos
+    }
+
+    func guardar(_ pedido: Pedido) async throws {
+        guardarLlamado = true
+        pedidoGuardado = pedido
+        if let error = errorALanzar { throw error }
+    }
+}
+
+// Uso en test
+let mock = MockPedidoRepository()
+mock.pedidos = [Pedido(id: UUID(), total: 150)]
+let vm = PedidoViewModel(repositorio: mock)
+await vm.cargar()
+XCTAssertEqual(vm.pedidos.count, 1)
+```
+
+---
+
+## Patrón Given-When-Then en XCTest
+
+```swift
+import XCTest
+
+final class CrearPedidoUseCaseTests: XCTestCase {
+
+    private var repositorioMock: MockPedidoRepository!
+    private var useCase: CrearPedidoUseCase!
+
+    override func setUp() {
+        super.setUp()
+        repositorioMock = MockPedidoRepository()
+        useCase = CrearPedidoUseCase(repositorio: repositorioMock)
+    }
+
+    override func tearDown() {
+        repositorioMock = nil
+        useCase = nil
+        super.tearDown()
+    }
+
+    func test_crearPedido_conItemsValidos_guardaYRetornaPedido() async throws {
+        // Given
+        let items = [ItemPedido(productoId: UUID(), cantidad: 2)]
+
+        // When
+        let pedido = try await useCase.ejecutar(items: items)
+
+        // Then
+        XCTAssertEqual(pedido.items.count, 1)
+        XCTAssertTrue(repositorioMock.guardarLlamado)
+        XCTAssertEqual(repositorioMock.pedidoGuardado?.id, pedido.id)
+    }
+
+    func test_crearPedido_sinItems_lanzaError() async {
+        // Given
+        let itemsVacios: [ItemPedido] = []
+
+        // When / Then
+        await XCTAssertThrowsError(
+            try await useCase.ejecutar(items: itemsVacios)
+        ) { error in
+            XCTAssertTrue(error is PedidoError)
+        }
+    }
+}
+```
+
+---
+
+## Snapshot testing para regresión visual
+
+```swift
+import SnapshotTesting
+
+final class PantallaPedidosSnapshotTests: XCTestCase {
+
+    func test_pantallaPedidos_estadoSuccess() {
+        // Given
+        let vm = PedidoViewModel(repositorio: MockPedidoRepository(pedidos: [.ejemplo]))
+        let vista = PantallaPedidos(viewModel: vm)
+        let vc = UIHostingController(rootView: vista)
+
+        // Then — genera o compara snapshot
+        assertSnapshot(of: vc, as: .image(on: .iPhone13Pro))
+    }
+}
+```
+
+Los archivos de snapshot se versionan en git bajo `__Snapshots__/`.
+Un snapshot que falla indica un cambio visual inesperado — revisar antes de actualizar.
+
+---
+
+## Tests de UI con XCUITest
+
+```swift
+final class FlujoCrearPedidoUITests: XCTestCase {
+
+    var app: XCUIApplication!
+
+    override func setUp() {
+        super.setUp()
+        continueAfterFailure = false
+        app = XCUIApplication()
+        app.launchArguments = ["--uitesting"]  // modo de test con datos mock
+        app.launch()
+    }
+
+    func test_crearPedido_flujoCompleto() {
+        // Given — pantalla de lista de pedidos
+        let botonNuevo = app.buttons["nuevo_pedido"]
+        XCTAssertTrue(botonNuevo.waitForExistence(timeout: 3))
+
+        // When — crear pedido
+        botonNuevo.tap()
+        app.textFields["campo_descripcion"].typeText("Pedido de prueba")
+        app.buttons["confirmar_pedido"].tap()
+
+        // Then — verificar que aparece en la lista
+        let textoPedido = app.staticTexts["Pedido de prueba"]
+        XCTAssertTrue(textoPedido.waitForExistence(timeout: 5))
+    }
+}
+```
+
+---
+
+## Cobertura con Xcode Coverage
+
+Habilitar en el esquema de Xcode: `Edit Scheme → Test → Code Coverage → Gather coverage`.
+
+Objetivo de cobertura por capa:
+- Capa de dominio (use cases, modelos): >= 90%
+- Capa de datos (repositorios, mappers): >= 80%
+- Capa de presentación (ViewModels): >= 80%
+- Vistas SwiftUI: snapshot tests cubren regresión visual
+
+---
+
+## Checklist de testing Swift antes de abrir PR
+
+- [ ] Tests usan `swift-testing` (Swift 6) o `XCTest` según target de deployment
+- [ ] Mocks implementados manualmente vía protocolos (sin frameworks)
+- [ ] Patrón Given-When-Then con comentarios explícitos
+- [ ] Cobertura de dominio y ViewModels >= 80%
+- [ ] Snapshots generados y versionados para vistas críticas
+- [ ] Tests de UI para flujos críticos con XCUITest
+- [ ] Sin `Thread.sleep()` ni delays fijos: usar `Task` y `await`
+- [ ] `setUp`/`tearDown` limpian estado entre tests

package/reglas/markitdown.md

@@ -0,0 +1,60 @@
+# Regla: Lectura de documentos Office y Jupyter con MarkItDown
+
+Esta regla aplica cuando un agente necesita **leer el contenido** de un archivo
+en formato Office o Jupyter. No aplica a operaciones de escritura, copia o listado.
+
+---
+
+## Cuándo aplica
+
+Cuando el agente necesita acceder al contenido de archivos con estas extensiones:
+
+| Extensión | Formato |
+|-----------|---------|
+| `.docx` | Word — documentos, especificaciones, ADRs |
+| `.xlsx` `.xls` | Excel — datos, métricas, matrices |
+| `.pptx` | PowerPoint — presentaciones, roadmaps |
+| `.ipynb` | Jupyter Notebook — análisis, experimentos |
+
+## Regla obligatoria
+
+NUNCA usar el Read tool directamente para estos formatos — no los soporta y
+devuelve contenido binario ilegible. Usar en su lugar:
+
+```bash
+# Opción 1: markitdown instalado globalmente (pip install markitdown)
+markitdown <ruta-al-archivo>
+
+# Opción 2: wrapper del vendor de swl-ses (si está disponible)
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+python "$PROJECT_ROOT/scripts/vendor/markitdown/cli.py" <ruta-al-archivo>
+
+# Opción 3: módulo Python directamente
+python -m markitdown <ruta-al-archivo>
+```
+
+**Verificar disponibilidad antes de usar**:
+```bash
+markitdown --version 2>/dev/null && echo "CLI_OK" || echo "NO_DISPONIBLE"
+```
+
+Si no está disponible:
+```
+markitdown no está instalado. Para habilitarlo:
+  pip install markitdown[pdf,docx,pptx,xlsx]
+
+Mientras tanto, pedir al usuario que proporcione el contenido en texto plano.
+```
+
+## Lo que sí usa el Read tool
+
+El Read tool sigue siendo correcto para:
+- `.pdf` (hasta 20 páginas con parámetro `pages:`)
+- `.md`, `.txt`, `.markdown`
+- Código fuente (`.py`, `.js`, `.ts`, `.java`, etc.)
+- Cualquier archivo de texto plano
+
+## Referencia completa
+
+Para casos avanzados (ingest masivo, URLs YouTube, ZIP con documentos mixtos,
+árbol de decisión completo): `Skill("swl-markitdown")`.

package/reglas/memoria-consolidada.md

@@ -0,0 +1,209 @@
+# Regla: Consolidación de memoria — dónde va cada dato
+
+Esta regla es **OBLIGATORIA** para todos los agentes, skills y comandos que
+escriben conocimiento persistente del sistema. Resuelve el problema de
+memoria fragmentada: SWL tiene 5 mecanismos de almacenamiento y sin una
+regla clara, un mismo dato puede terminar en el lugar incorrecto o duplicado.
+
+---
+
+## Los 5 canales de memoria
+
+| # | Canal | Formato | Fuente de verdad de |
+|---|-------|---------|---------------------|
+| 1 | **Memoria nativa de Claude Code** (`~/.claude/projects/.../memory/`) | Archivos `.md` con frontmatter `user`/`feedback`/`project`/`reference` | Perfil general del usuario y del proyecto, auto-gestionado por el harness |
+| 2 | **`.planning/APRENDIZAJES.md`** | Markdown con entradas `### [YYYY-MM-DD] Título` agrupadas por sección | Conocimiento del dominio (anti-patrones, patrones, decisiones, gotchas) |
+| 3 | **`instintos/proyecto.yaml` / `global.yaml` / `perfil-usuario.yaml`** | YAML estructurado con confidence, scope, evidence_count | Patrones aprendidos inductivamente, con promoción/degradación |
+| 4 | **`.planning/sessions/search-index.json`** | Índice FTS de sesiones pasadas | Búsqueda histórica de trabajo (qué se hizo, cuándo) |
+| 5 | **`.planning/evolucion/*`** | JSONL (nudges, agentes) + JSON (métricas, alertas, evoluciones) | Estado del ciclo de auto-evolución |
+
+---
+
+## Regla de asignación — dónde va CADA tipo de dato
+
+### A. Información del usuario
+
+| Tipo de dato | Canal correcto | NO va a |
+|---|---|---|
+| Rol profesional, años de experiencia | 1 (memoria `user`) + 3 (perfil-usuario.yaml) | APRENDIZAJES, sessions, proyecto.yaml |
+| Stack preferido del usuario | 3 (perfil-usuario.yaml) | APRENDIZAJES |
+| Corrección explícita del usuario ("prefiero X", "nunca Y") | 1 (memoria `feedback`) + 3 (perfil-usuario.yaml vía perfilador-usuario-swl) | APRENDIZAJES |
+| Preferencia de idioma, formalidad, longitud | 3 (perfil-usuario.yaml) | — |
+| Límites explícitos ("no guardes X") | 3 (perfil-usuario.yaml `limites_explicitos`) | — |
+
+### B. Conocimiento del dominio (aplicable al proyecto o transversal)
+
+| Tipo de dato | Canal correcto | NO va a |
+|---|---|---|
+| Anti-patrón descubierto (ej: bug recurrente) | 2 (APRENDIZAJES.md sección "Anti-patrones") | perfil-usuario, instintos directamente |
+| Patrón exitoso reutilizable | 2 (APRENDIZAJES.md) → eventual skill nuevo (tipo C) | perfil-usuario |
+| Decisión de arquitectura tomada | 2 (APRENDIZAJES.md sección "Decisiones") + eventualmente CLAUDE.md | perfil-usuario, instintos sin consolidar primero |
+| Gotcha específico de una librería | 2 (APRENDIZAJES.md) o skill existente | perfil-usuario |
+
+### C. Estado del sistema y observabilidad
+
+| Tipo de dato | Canal correcto |
+|---|---|
+| Nudge emitido por un hook | 5 (`.planning/evolucion/nudges.jsonl`) |
+| Evento de subagente terminado | 5 (`.planning/auto-evolucion/agentes.jsonl`) |
+| Evolución aplicada/revertida a skill | 5 (`.planning/evolucion/evoluciones.jsonl`) |
+| Alerta persistente (nudges ignorados) | 5 (`.planning/evolucion/alertas-persistentes.json`) |
+| Métricas agregadas (health score) | 5 (`.planning/evolucion/metricas.json`) |
+| Traza de ejecución de agente | `.planning/traces/` (OTLP-lite) |
+| Audit trail inmutable | `.planning/audit.jsonl` + Merkle |
+
+### D. Patrones consolidados (inductivos, con confidence)
+
+| Tipo de dato | Canal correcto |
+|---|---|
+| Patrón observado ≥1 vez con confidence < 0.5 | 3 (instintos/proyecto.yaml como draft) |
+| Patrón consolidado (confidence ≥ 0.5, evidence_count ≥ 3) | 3 (instintos/proyecto.yaml activo) |
+| Patrón validado cross-proyecto (confidence > 0.8) | 3 (instintos/global.yaml tras promoción) |
+| Patrón contradicho (degradado ≥3 veces) | 3 (instintos/proyecto.yaml status `degraded`) o borrado |
+
+### E. Búsqueda histórica
+
+| Tipo de dato | Canal correcto |
+|---|---|
+| "¿Qué hicimos la semana pasada en X?" | 4 (sessions/search-index.json) — vía `habilidades/memoria-busqueda` |
+| Sesión completa archivada | `.planning/sessions/*.json` |
+
+---
+
+## Precedencia en caso de conflicto
+
+Si un mismo dato aparece en múltiples canales, la prioridad de verdad es:
+
+```
+CLAUDE.md (regla explícita)
+  > Memoria nativa tipo feedback del usuario (corrección explícita)
+  > instintos con confidence ≥ 0.9
+  > APRENDIZAJES.md (si es tipo Decisión)
+  > perfil-usuario.yaml
+  > instintos con confidence < 0.9
+  > sesiones pasadas
+```
+
+---
+
+## Reglas de no-duplicación
+
+1. **Un dato vive en exactamente un canal** (salvo referencias explícitas).
+   Si necesitas citarlo desde otro, usa un puntero/path, no copies el contenido.
+
+2. **perfil-usuario.yaml NUNCA duplica APRENDIZAJES.md.** Una corrección del
+   usuario va al perfil; un anti-patrón técnico va a APRENDIZAJES.
+
+3. **instintos/proyecto.yaml bootstrap desde APRENDIZAJES.md** es válido
+   (hace `scripts/bootstrap-instintos.js`), pero la fuente de verdad post-bootstrap
+   es `instintos/proyecto.yaml`. Nuevos APRENDIZAJES no deben entrar a instintos
+   automáticamente — primero se promueven con `/swl:aprender` (tipo C).
+
+4. **La memoria nativa del harness no se sobreescribe** con contenido de SWL.
+   El flujo es al revés: señales del usuario pueden alimentar ambos canales
+   (native + perfil SWL), pero ninguno es copia del otro.
+
+5. **Cuando detectes duplicación cross-canal**, registrarla como anti-patrón
+   en APRENDIZAJES.md y corregir con `scripts/validar-memoria.js`.
+
+---
+
+## Validación automática
+
+El script `scripts/validar-memoria.js` detecta duplicaciones y violaciones
+de esta regla. Se ejecuta:
+
+- Manualmente: `node scripts/validar-memoria.js`
+- Automáticamente dentro de `scripts/validar.js` (parte del pipeline CI)
+
+Reporta: duplicación cross-canal, canal incorrecto para un tipo de dato
+conocido, datos en canales deprecados.
+
+---
+
+## Anti-patrones a detectar
+
+- **Corrección del usuario escrita a APRENDIZAJES.md** → debe ir al perfil
+- **Anti-patrón técnico escrito al perfil del usuario** → debe ir a APRENDIZAJES
+- **Métrica persistida en APRENDIZAJES.md** → debe ir a `.planning/evolucion/`
+- **Secreto/credencial en cualquier canal** → bloqueo inmediato (`privacy-memoria`)
+- **Dato duplicado en proyecto.yaml y global.yaml** → uno debe borrarse
+  (promover a global SOLO cuando confidence > 0.8 Y validado cross-proyecto)
+- **Instinto activo con `last_validated` antiguo (>180 días) sin feedback**
+  → el `effective_confidence` ya está bajo `0.25`. Re-validar manualmente o
+  marcar `status: archived`.
+
+---
+
+## Scoring de instintos: decay exponencial + maturity
+
+El campo `confidence` en instintos es **estático** (asignado al crear). El valor
+**efectivo** se computa dinámicamente con dos factores:
+
+1. **Decay temporal**: la confianza decae exponencialmente desde `last_validated_at`.
+   Half-life por defecto: 90 días. Tras 1 half-life → confianza × 0.5; tras 2 → × 0.25.
+2. **Penalización por feedback dañino**: si `harmful_count / (helpful_count + harmful_count) > 0.3`
+   con al menos 3 eventos, el instinto se propone para `status: degraded`.
+
+Implementación pura en `scripts/lib/scoring-instintos.js`:
+
+```js
+const { effectiveConfidence, maturityState, applyFeedback } = require('./scoring-instintos');
+
+// Lectura
+const eff = effectiveConfidence(instinto, new Date());
+const maturity = maturityState(instinto, new Date());
+// → 'candidate' | 'established' | 'proven' | 'deprecated'
+
+// Escritura (pure)
+const conFeedback = applyFeedback(instinto, 'helpful');
+```
+
+**Cuándo recomputar**:
+- `/swl:salud` reporta instintos con `effective_confidence < 0.3` para revisión.
+- `hooks/degradacion-instintos.js` puede marcar `status_proposed: degraded`
+  cuando `shouldAutoDeprecate(instinto)` devuelve `true`.
+- `bootstrap-instintos.js` emite los nuevos instintos con `decay_half_life_days: 90`,
+  `helpful_count: 0`, `harmful_count: 0` por defecto.
+
+**Backward compat**: instintos antiguos sin los campos nuevos siguen siendo
+válidos. `effectiveConfidence` cae a `confidence * decay` cuando no hay feedback,
+y `last_validated` (sin `_at`) se usa como fallback.
+
+---
+
+## Source tracing en instintos y APRENDIZAJES
+
+Cada instinto puede declarar la **evidencia que lo respalda** mediante:
+
+- `source_sessions: ["sess-abc", "sess-def"]` — sesiones que lo generaron o validaron
+- `source_agents: ["orquestador-swl", "implementador-swl"]` — agentes que lo aplicaron exitosamente
+- `evidence_count: N` — total numérico (compatibilidad legacy)
+
+**Reglas**:
+
+1. Un instinto con `confidence ≥ 0.7` debe tener al menos 1 entrada en
+   `source_sessions` o `source_agents` para justificar la confianza.
+2. Para promover de `instintos/proyecto.yaml` a `instintos/global.yaml`, el
+   instinto debe tener `source_agents.length ≥ 2` o `source_sessions.length ≥ 3`
+   — un solo punto de evidencia no es suficiente para impacto cross-proyecto.
+3. El campo `source_sessions` referencia IDs de `.planning/sessions/`. No copiar
+   el contenido — usar el ID como puntero.
+4. `addSource()` en `scripts/lib/scoring-instintos.js` mantiene unicidad
+   automática. NUNCA editar manualmente con duplicados.
+
+**Anti-patrón**: instinto con `evidence_count: 10` pero `source_sessions: []` y
+`source_agents: []` — la cifra es opaca, no se puede auditar de dónde viene.
+
+---
+
+## Checklist antes de escribir a memoria
+
+Antes de que cualquier agente, skill o hook persista un dato, debe responder:
+
+1. ¿Es información del **usuario**, del **dominio**, de **estado del sistema**,
+   un **patrón inductivo**, o **búsqueda histórica**? → identifica canal A-E.
+2. ¿El canal elegido es el correcto según la tabla de asignación?
+3. ¿El dato ya existe en otro canal? Si sí, actualiza ese, no dupliques.
+4. ¿El dato contiene PII, secretos o contenido sensible? → cargar `privacy-memoria`.
+5. ¿El dato viene de texto del usuario? → escanear con `prompt-injection-scanner`.