# 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`.
