@saulwade/swl-ses 1.9.0 → 2.1.0

package/reglas/accesibilidad.md

@@ -1,3 +1,13 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.vue"
+  - "**/*.svelte"
+  - "**/*.html"
+  - "**/*.css"
+  - "**/*.scss"
+---
 # Regla: Accesibilidad
 
 Esta regla es OBLIGATORIA para todo código frontend sin excepción.

package/reglas/analizar-directorios-antes-de-escribir.md

@@ -0,0 +1,228 @@
+# Regla: Analizar la estructura de directorios antes de escribir documentación o MDs
+
+Esta regla es OBLIGATORIA y aplica cada vez que Claude va a **crear un
+directorio nuevo** o **escribir un archivo de documentación** (`.md`, `.json`
+de reporte, informe, ADR, plan, análisis, output de auditoría/diseño/research)
+en cualquier proyecto del usuario.
+
+Cierra un patrón conductual recurrente: el agente escribe un documento en un
+directorio nuevo elegido ad-hoc — en idioma o nombre distinto al que el
+proyecto ya usa para ese dominio — y produce **directorios paralelos
+divergentes** que fragmentan la memoria institucional.
+
+---
+
+## Principio
+
+> Antes de crear un directorio nuevo o escribir un MD/reporte, **analiza
+> primero la estructura de directorios existente** (`Glob`/`ls`) para
+> descubrir la convención que el proyecto YA usa para ese dominio, y
+> **reúsala**. NUNCA crees un directorio paralelo para un dominio que ya
+> tiene uno. Solo cuando no exista precedente, crea uno nuevo siguiendo la
+> convención dominante del proyecto; como desempate del **nombre**, prefiere
+> español de México — salvo que exista un path canónico establecido (aunque
+> sea en inglés), en cuyo caso ese path gana.
+
+El costo de un `ls` antes de escribir es de 1 segundo. El costo de un
+directorio paralelo es: referencias colgadas, búsquedas que fallan, memoria
+institucional partida, y una sesión futura de depuración/unificación.
+
+---
+
+## Cuándo aplicar
+
+OBLIGATORIO antes de:
+
+- Escribir un reporte de auditoría, verificación, nemesis, revisión, análisis.
+- Escribir un documento de diseño/UX (propuesta, tokens, discovery, UI-SPEC).
+- Crear un ADR, plan, spec, runbook, research output.
+- Crear cualquier directorio nuevo bajo `.planning/`, `docs/`, o equivalente.
+- Persistir cualquier `.md`/`.json` que sea memoria del proyecto (no código).
+
+NO aplica cuando:
+
+- El comando/agente/herramienta **fija un path canónico de output** — en ese
+  caso úsalo tal cual, no lo cuestiones (ej: un agente que pinea
+  `.planning/audit/findings/iter-N/`).
+- El archivo es código fuente (sigue las convenciones del lenguaje/framework).
+- El usuario indicó explícitamente la ruta exacta donde escribir.
+- Es un archivo efímero de scratch que se borrará en el mismo turno.
+
+---
+
+## Cómo aplicar — protocolo de 4 pasos
+
+### Paso 1 — Listar la estructura existente
+
+Antes de elegir dónde escribir:
+
+```bash
+ls .planning/          # o el directorio raíz de docs del proyecto
+ls docs/
+```
+
+O con Glob: `**/{audit,auditoria,diseno*,ux,design,research,specs}/`.
+
+### Paso 2 — Buscar si el dominio ya tiene directorio (incluye variantes es/en)
+
+Pregúntate: ¿ya existe un directorio para este tipo de artefacto? Busca
+**variantes en ambos idiomas** y sinónimos:
+
+| Dominio | Variantes a buscar antes de crear |
+|---|---|
+| Auditoría | `audit/`, `auditoria/`, `auditorias/`, `findings/` |
+| Diseño/UX | `diseno/`, `diseno-visual/`, `ux/`, `ui/`, `design/` |
+| Investigación | `research/`, `investigacion/`, `knowledge/` |
+| Decisiones | `adrs/`, `adr/`, `decisiones/` |
+| Sesiones | `sessions/`, `sesiones/` |
+| Deuda | `DEUDAS.md`, `DEUDA-TECNICA.md`, `deuda/`, `debt/` |
+
+### Paso 3 — Decidir el destino
+
+- **Si ya existe un directorio para el dominio** → escribe ahí. Punto. Aunque
+  el nombre existente esté en el "idioma equivocado", reusarlo es superior a
+  crear un paralelo. La consistencia gana sobre la preferencia de idioma.
+- **Si existe un path canónico de la herramienta** (swl-ses pinea
+  `.planning/audit/`, `knowledge/outputs/`, `sessions/`, etc.) → ese path es
+  la fuente de verdad. NO lo dupliques en español.
+- **Si NO existe precedente** → crea uno nuevo siguiendo la convención
+  dominante del proyecto (mira cómo están nombrados los directorios hermanos).
+
+### Paso 4 — Desempate del nombre (solo para directorios genuinamente nuevos)
+
+Cuando creas un nombre nuevo sin precedente ni path canónico:
+
+- Prefiere **español de México** (consistente con
+  `~/.claude/rules/brevedad-output.md § Idioma obligatorio`): `diseno/`,
+  `investigacion/`, `auditoria/` antes que `design/`, `research/`, `audit/`.
+- **PERO**: si el proyecto ya tiene una convención de idioma dominante para
+  sus directorios (ej: swl-ses usa mayormente inglés: `audit/`, `knowledge/`,
+  `sessions/`, `research/`), respeta ESA convención sobre la preferencia
+  general — la coherencia intra-proyecto manda.
+- Identificadores técnicos (nombres que un comando/script consume como string)
+  siguen la convención del consumidor, no la preferencia de idioma.
+
+---
+
+## La tensión es/en — cómo resolverla (no es "español siempre")
+
+"Preferir español" es un **desempate**, no un mandato absoluto. La jerarquía
+de decisión, de mayor a menor prioridad:
+
+1. **Path canónico fijado por la herramienta** (gana siempre, aunque sea inglés).
+2. **Directorio existente para el dominio** (reusar, aunque el idioma "no cuadre").
+3. **Convención de idioma dominante del proyecto** (si el proyecto es es → es;
+   si es en → en).
+4. **Preferencia general español de México** (solo cuando 1-3 no aplican).
+
+Renombrar un path canónico inglés establecido a español **viola** esta regla:
+reintroduce divergencia en vez de eliminarla. El objetivo es UNA convención por
+proyecto, no "todo en español".
+
+
+---
+
+## Eje técnico-runtime vs vocabulario-de-dominio (refina la jerarquía)
+
+La jerarquía de arriba decide entre español e inglés *cuando todo el árbol usa
+un solo idioma*. Pero muchos proyectos adoptan una convención **mixta por
+categoría**: "identificadores técnicos en inglés, vocabulario de cara al usuario
+en el idioma del proyecto" (caso swl-ses). Ahí, **clasifica el directorio ANTES**
+de aplicar la jerarquía:
+
+- **Path runtime/técnico → inglés.** Telemetría, estado interno, caches, logs
+  archivados, outputs de tooling, índices. No los lee el usuario final; los
+  consume el código como string. Ej. en swl-ses: `.planning/evolution/`,
+  `.planning/auto-evolution/`, `.planning/user-profile/`, `.planning/archive/`,
+  `.planning/traces/`, `.planning/sessions/`, `.planning/audit/`.
+- **Vocabulario de dominio de cara al usuario → idioma del proyecto.** Artefactos
+  acoplados a comandos/UX cuyo nombre el usuario lee y escribe. Ej. en swl-ses:
+  `.planning/fases/` permanece **español** porque su comando es `/swl:planear-fase`
+  (español, intocable). Cambiar el dir sin cambiar el comando crea una
+  inconsistencia comando↔directorio *peor* que la divergencia que se quería evitar.
+
+**Regla de coherencia comando↔directorio:** el nombre del data dir debe espejar
+el idioma del comando que escribe en él. NUNCA partir un par comando↔directorio
+en dos idiomas.
+
+**Consolidar islas runtime SÍ es válido (no viola "no renombrar paths
+establecidos"):** si un proyecto con convención técnico-inglés tiene islas
+runtime en español (`evolucion/`, `archivo/`), alinearlas a inglés *reduce*
+divergencia — es lo opuesto a "renombrar `audit/` a español". La prohibición de
+renombrar aplica a mover *desde* la convención establecida, no *hacia* ella. Las
+islas runtime alineadas requieren shim de migración (renombrar el dir físico en
+proyectos que ya tienen datos) — ver `scripts/instalador.js § 6c-bis` en swl-ses.
+
+
+---
+
+## Anti-patrones explícitos
+
+- **Crear `ux/` cuando ya existe `diseno-visual/`** (o viceversa) sin haber
+  hecho `ls .planning/` primero. Caso real: SIGM acumuló ambos por sesiones
+  distintas que no verificaron el precedente.
+- **Crear `auditoria/` (es) cuando la herramienta pinea `audit/` (en)** como
+  path canónico. Caso real: `/swl:verificar` y el consolidado de `/swl:nemesis`
+  escribieron en `auditoria/` mientras los reportes por-router iban a
+  `audit/findings/` — misma corrida, dos directorios.
+- **Renombrar `audit/`, `knowledge/`, `sessions/` a español** "porque la
+  preferencia es español". Eso rompe paths canónicos y reintroduce divergencia.
+- **Escribir un reporte en un directorio top-level nuevo** sin revisar los
+  directorios hermanos existentes.
+- **Asumir que no hay precedente sin buscar variantes es/en** del nombre del
+  dominio.
+
+---
+
+## Excepciones legítimas
+
+NO aplicar (o aplicar con criterio reducido) cuando:
+
+1. El comando/agente **pinea el path** — úsalo, no analices.
+2. El usuario dictó la ruta exacta.
+3. Es un archivo de scratch efímero del mismo turno.
+4. Es el **primer** documento del proyecto (no hay estructura que analizar
+   todavía) — ahí creas la convención; hazlo deliberadamente y en español si
+   no hay restricción técnica.
+
+---
+
+## Checklist antes de escribir un MD/reporte o crear un directorio
+
+- [ ] Ejecuté `ls`/`Glob` sobre el directorio raíz de docs (`.planning/`, `docs/`).
+- [ ] Busqué variantes es/en del nombre del dominio (audit/auditoria,
+      diseno/ux/design, research/investigacion).
+- [ ] Si existe directorio para el dominio → escribo ahí (no creo paralelo).
+- [ ] Si la herramienta pinea path canónico → uso ese (aunque sea inglés).
+- [ ] Si creo uno nuevo → sigue la convención de idioma dominante del proyecto;
+      español como desempate solo sin precedente ni path canónico.
+- [ ] No reintroduje divergencia renombrando un path canónico establecido.
+
+---
+
+## Origen de esta regla
+
+Sesión 2026-05-31, proyecto SIGM. Al depurar `.planning/` se detectaron **dos
+pares de directorios divergentes** creados por sesiones distintas para el mismo
+dominio, en idiomas distintos:
+
+- `.planning/audit/` (en, canónico swl-ses) vs `.planning/auditoria/` (es,
+  ad-hoc). La misma corrida de `/swl:nemesis` quedó partida entre ambos; 8
+  documentos con referencias colgadas tras la consolidación.
+- `.planning/ux/` (en, 2026-05-30) vs `.planning/diseno-visual/` (es,
+  2026-05-11). La sesión 05-30 creó `ux/` sin verificar que `diseno-visual/`
+  ya existía.
+
+Causa raíz dual: (a) **conductual** — el agente no analiza la estructura
+existente antes de escribir (esta regla); (b) **de herramienta** — varios
+comandos/agentes de swl-ses no fijan path canónico de output (ticket
+`DT-PLANNING-OUTPUT-PATHS` en swl-ses). Esta regla ataca el lado conductual y
+aplica a todo proyecto del usuario, use o no swl-ses.
+
+Relación con otras reglas:
+- `~/.claude/rules/brevedad-output.md § Idioma obligatorio` — la preferencia
+  español que esta regla usa como desempate.
+- `~/.claude/rules/memoria-consolidada.md § no-duplicación` — un dato vive en
+  un solo canal; esta regla extiende el principio a directorios.
+- `~/.claude/rules/sin-duplicacion-reglas-globales.md` — analogía: no duplicar
+  contenido que ya vive en su lugar canónico.

package/reglas/api-diseno.md

@@ -1,3 +1,12 @@
+---
+paths:
+  - "**/api/**"
+  - "**/routers/**"
+  - "**/controllers/**"
+  - "**/handlers/**"
+  - "**/endpoints/**"
+  - "**/openapi.{yaml,yml,json}"
+---
 # Regla: Diseño de APIs REST
 
 Esta regla es OBLIGATORIA para toda API REST expuesta, ya sea pública o interna.

package/reglas/auditorias-documentales-estructurales.md

@@ -1,3 +1,10 @@
+---
+paths:
+  - "**/scripts/verificar-*.js"
+  - "**/MANUAL_USO.md"
+  - "**/manifiestos/**"
+  - "**/INVENTARIO.md"
+---
 # Regla: Auditorías documentales estructurales en SWL
 
 Esta regla es **OBLIGATORIA** y aplica a todo agente o agente humano que

package/reglas/cloud-infra.md

@@ -1,3 +1,11 @@
+---
+paths:
+  - "**/*.tf"
+  - "**/*.tfvars"
+  - "**/Dockerfile*"
+  - "**/*.bicep"
+  - "**/docker-compose*.{yml,yaml}"
+---
 # Regla: Infraestructura Cloud
 
 Esta regla es OBLIGATORIA para todo recurso desplegado en cloud sin excepción.

package/reglas/consultar-vault-primero.md

@@ -0,0 +1,195 @@
+# Regla: Consultar el vault Obsidian antes de leer múltiples archivos
+
+Esta regla es OBLIGATORIA y aplica cuando Claude necesita contexto de dominio
+(arquitectura, decisiones, patrones, lecciones, vocabulario del proyecto) antes
+de implementar, debugear, planificar o responder preguntas no triviales.
+
+El vault Obsidian del usuario es **fuente de verdad curada**: contiene resúmenes,
+ADRs, notas de decisiones, índices de proyectos, lecciones aprendidas. Está
+indexado y consultable vía MCP server `obsidian`. Leer ahí primero es más
+eficiente en tokens que leer múltiples archivos del codebase.
+
+---
+
+## Principio
+
+> Antes de leer **3 o más archivos completos** del codebase para construir
+> contexto general (arquitectura, decisiones previas, convenciones del proyecto,
+> patrones), **consulta el vault Obsidian primero** con `obsidian_simple_search`
+> o `obsidian_complex_search`. Lee únicamente las notas relevantes. Solo cae
+> al codebase para los detalles concretos que el vault no cubra.
+
+Esto reduce el contexto consumido y aprovecha el conocimiento que el usuario ya
+sintetizó manualmente.
+
+---
+
+## Cuándo aplicar
+
+OBLIGATORIO consultar el vault antes de:
+
+- Empezar una sesión nueva en un proyecto donde el usuario menciona terminología
+  específica (nombres de sistemas, ADRs, conceptos del dominio)
+- **Tomar una decisión de diseño, arquitectura o scope** — en CUALQUIER
+  proyecto, no solo en uno desconocido. El usuario tiene decisiones ya tomadas
+  que se repiten y no quiere reabrirlas
+- Buscar el "por qué" detrás de una elección arquitectónica
+- Resolver un bug donde la causa puede estar documentada en lecciones aprendidas
+- Investigar si un patrón ya fue evaluado y descartado
+- Responder "¿qué dice tu sistema sobre X?" o "¿cómo manejamos Y?"
+- **Antes de proponer una solución que parece "obvia"** — si suena obvia, alta
+  probabilidad de que el usuario ya pasó por ahí y haya una decisión documentada
+
+NO aplicar cuando:
+
+- La tarea es claramente local a 1-2 archivos del codebase (fix puntual, rename)
+- El usuario pidió explícitamente leer un archivo específico
+- Es una operación de comando puro (git, npm install, builds)
+- El proyecto no es del usuario (repos de terceros, código de exploración)
+
+---
+
+## Tipos de conocimiento valioso que el vault repite
+
+El vault no es archivo histórico — es **memoria operacional activa**. Los
+siguientes tipos de contenido se repiten a través de proyectos y sesiones:
+
+| Tipo | Por qué consultarlo | Ejemplo de query |
+|---|---|---|
+| **ADRs vigentes y propuestos** | Decisiones de arquitectura que el usuario YA tomó y no quiere debatir otra vez | `obsidian_simple_search` con nombre del componente o tecnología |
+| **Patrones validados** | Soluciones que el usuario aprobó en sesiones previas para problemas equivalentes | búsqueda por keyword del problema |
+| **Anti-patrones documentados** | Caminos que el usuario YA rechazó — proponerlos otra vez es regresión | búsqueda por síntoma del bug o patrón |
+| **Vocabulario y convenciones del dominio** | Términos específicos del proyecto (OIC, VBO, papel de trabajo) que tienen significado preciso | nombre del término |
+| **Lecciones de incidentes** | Bugs ya investigados con causa raíz documentada | búsqueda por mensaje de error o síntoma |
+| **Diferencias entre proyectos del usuario** | SIGAF vs SIGM vs swl-ses tienen convenciones distintas — el vault las separa | path filtering por carpeta del proyecto |
+| **Roadmap y prioridades** | Lo que el usuario quiere para próximos sprints vs lo que está cerrado | búsqueda por nombre de feature |
+
+**Regla práctica**: si la decisión que vas a tomar es del tipo "el usuario
+probablemente ya pensó en esto", consulta antes. La probabilidad de que
+exista nota relevante en el vault es alta.
+
+---
+
+## Cómo consultar
+
+### Tools disponibles del MCP `obsidian`
+
+| Tool | Cuándo usar |
+|---|---|
+| `obsidian_simple_search` | Búsqueda full-text por keywords. Primer paso siempre. |
+| `obsidian_complex_search` | Filtros estructurados (frontmatter, tags, paths). Cuando simple_search devuelve demasiado. |
+| `obsidian_list_files_in_vault` | Inventario completo del vault. Solo en sesión inicial de un proyecto. |
+| `obsidian_list_files_in_dir` | Listar notas de una carpeta específica. |
+| `obsidian_get_file_contents` | Leer una nota completa identificada por path relativo al vault. |
+| `obsidian_recent_changes` | Notas modificadas recientemente. Útil para retomar trabajo reciente. |
+| `obsidian_periodic_notes` | Daily/weekly notes si el usuario las usa. |
+
+### Workflow estándar
+
+1. **Search**: `obsidian_simple_search` con 2-4 keywords del dominio del problema.
+2. **Triage**: revisar paths de las notas devueltas. Identificar las 1-3 más
+   relevantes por nombre de archivo y context score.
+3. **Read targeted**: `obsidian_get_file_contents` solo de esas 1-3 notas.
+4. **Fallback al codebase**: si el vault no tiene info suficiente, ahí sí leer
+   archivos del codebase — pero con foco específico, no exploración amplia.
+
+### Anti-patrones
+
+- ❌ Leer 5+ archivos del codebase para entender la arquitectura sin haber
+  consultado el vault primero.
+- ❌ Llamar `obsidian_list_files_in_vault` y leer todo — el vault puede tener
+  cientos de notas. Usar search siempre antes que list.
+- ❌ Ignorar el vault porque "el codebase es fuente de verdad" — el codebase
+  es la fuente de verdad del CÓDIGO; el vault es la fuente de verdad de las
+  DECISIONES y el CONTEXTO.
+- ❌ Re-leer la misma nota del vault en turnos sucesivos del mismo proyecto —
+  el contenido ya está en contexto, citarlo directamente.
+- ❌ **Re-abrir una decisión ya documentada en el vault** porque "no la
+  recuerdo en este turno". Si la decisión está en una nota del usuario,
+  consultarla en lugar de re-debatir el tradeoff desde cero. El usuario
+  ya pagó el costo de decidir — no obligarlo a re-pagar.
+- ❌ **Proponer una solución sin verificar si el vault tiene una nota
+  contraria**. Si el usuario propuso X hace 2 meses y lo rechazó por razón
+  Y documentada en el vault, proponer X otra vez es regresión silenciosa.
+- ❌ **Asumir que "es un proyecto nuevo, no hay nada en el vault"** sin
+  buscar. El vault tiene notas transversales (decisiones arquitectónicas
+  del usuario, convenciones de naming, stack preferido) que aplican
+  cross-proyecto.
+- ❌ **Defaultear a Bash+filesystem cuando los tools `mcp__obsidian__*`
+  aparecen como deferred ("schemas not loaded")**. Tools deferred ≠ tools
+  ausentes — el MCP server está corriendo, solo falta cargar schemas vía
+  `ToolSearch(query="select:mcp__obsidian__obsidian_simple_search", ...)`.
+  Si Bash+cp+heredoc parece "más fácil", es inercia del workaround antiguo.
+  La ruta MCP es **siempre superior** para escritura al vault: patches
+  dirigidos por sección con `obsidian_patch_content` (target_type heading),
+  sin staging intermedio, sin tocar `proteccion-rutas.js`, auditable
+  nativamente por el plugin Local REST API.
+- ❌ **Tras un bloqueo de hook hacia el vault, recurrir al workaround
+  conocido sin reconsiderar el canal nuevo**. El MCP `obsidian` opera vía
+  HTTPS al puerto 27124 — NO pasa por el hook `proteccion-rutas.js`
+  (es protocolo MCP, no operación de filesystem). Cuando un destino esté
+  fuera del CWD, evaluar primero `mcp__obsidian__*` antes de defaultear
+  a Bash + cp.
+
+### Workflow forzoso para escritura al vault
+
+Si la operación es **escribir** al vault (no solo leer):
+
+1. Verificar si los tools `mcp__obsidian__obsidian_patch_content` y
+   `mcp__obsidian__obsidian_append_content` están cargados.
+2. Si aparecen como deferred → invocar `ToolSearch` con
+   `select:<tool-name>` para cargar el schema.
+3. Solo si el MCP no responde tras 5s o no está registrado → caer al
+   filesystem como fallback con disclaimer al usuario ("MCP no disponible,
+   uso filesystem y staging").
+4. NUNCA escribir al vault vía Bash + heredoc + cp como primera opción
+   cuando el MCP está disponible. Es deuda operativa con costo en cada
+   sesión futura.
+
+---
+
+## Vault del usuario
+
+- **Path**: `F:\Google Drive\Developer\Obsidian\Vault\SWL` (sincronizado vía
+  Google Drive entre WISC y WISCLAP)
+- **Contenido típico**: notas sobre el sistema SWL, decisiones de arquitectura,
+  ADRs, lecciones de sesiones pasadas, vocabulario específico del dominio
+- **Plugin habilitador**: Local REST API en Obsidian (puerto 27124, HTTPS)
+- **Precondición**: Obsidian debe estar corriendo en la máquina actual para
+  que el MCP responda. Si no responde, fallback al codebase con disclaimer
+  al usuario ("Obsidian no está corriendo, no pude consultar el vault").
+
+---
+
+## Excepciones documentadas
+
+- Si `obsidian_simple_search` devuelve 0 resultados para keywords razonables
+  del dominio, el vault no cubre el tema — proceder con codebase sin más
+  intentos en el vault.
+- Si Obsidian no está corriendo (timeout o connection refused), reportarlo
+  al usuario en una línea breve y proceder con codebase. NO bloquear el flujo.
+- Para tareas donde el usuario explícitamente dice "no consultes nada, solo
+  haz X", respetar — esto es preferencia explícita.
+
+---
+
+## Aplicabilidad
+
+Esta regla aplica a:
+- Claude Code (CLI y Desktop)
+- Cualquier agente del sistema SWL que necesite contexto de dominio
+- Sesiones de planning, debugging, arquitectura, code review
+
+NO aplica a:
+- Sub-agentes que solo hacen una tarea atómica (formateo, lint, build)
+- Agentes que operan exclusivamente sobre archivos pasados como argumento
+
+---
+
+## Origen
+
+Formalizada el 2026-05-09 al instalar el MCP server `mcp-obsidian` (Python,
+MarkusPfundstein) en WISCLAP para evitar el patrón observado de leer múltiples
+archivos del codebase para reconstruir contexto que ya estaba sintetizado en
+el vault. La regla aplica cross-machine vía Syncthing (`~/.claude/rules/` se
+sincroniza automáticamente).

package/reglas/debatir-antes-de-aceptar.md

@@ -0,0 +1,158 @@
+# Regla: Debatir antes de aceptar decisiones que chocan con reglas
+
+Esta regla es OBLIGATORIA y aplica a todo trabajo donde Claude reciba una
+decisión técnica o de diseño del usuario que entre en conflicto con una regla
+documentada del sistema, una invariante del dominio, o una buena práctica
+establecida.
+
+---
+
+## Principio
+
+> Cuando el usuario propone una decisión, **NUNCA la aceptes por reflejo**.
+> Si la decisión choca con una regla documentada (de `~/.claude/rules/`,
+> `CLAUDE.md` del proyecto, ADRs vigentes) o con una invariante obvia del
+> dominio, debes **debatirla con cita concreta + riesgo observable +
+> alternativa** ANTES de implementar.
+
+El usuario espera un colaborador técnico, no un sí-señor. Su rol es decidir
+qué riesgos asume; el rol del agente es señalar el costo técnico antes de
+que la decisión se materialice.
+
+---
+
+## Cuándo aplicar
+
+Cuando la decisión del usuario:
+
+- Contradice una regla global de `~/.claude/rules/*.md` (especialmente
+  `seguridad-agentes.md`, `arquitectura.md`, `gobernanza.md`, `seguridad.md`).
+- Contradice una regla de `CLAUDE.md` del proyecto o un ADR vigente.
+- Rompe una invariante del dominio (integridad referencial, auditoría
+  inmutable, trazabilidad regulatoria, separación de responsabilidades).
+- Introduce una "puerta trasera" para un rol privilegiado que erosiona una
+  garantía formal del sistema (ej: ADMIN bypassa una invariante de
+  integridad — distinto de bypassar una restricción jerárquica).
+
+---
+
+## Cómo aplicar
+
+### Paso 1 — Contrastar la decisión con las reglas
+
+Antes de implementar, ejecuta mentalmente este check:
+
+- ¿Existe una regla en `~/.claude/rules/` que aplique?
+- ¿El proyecto tiene `CLAUDE.md` o ADRs que cubran este territorio?
+- ¿La decisión rompe una invariante visible del dominio (audit trail,
+  consistencia de estados, integridad referencial)?
+- ¿Hay un ejemplo histórico en el proyecto donde una decisión similar
+  causó un incidente?
+
+### Paso 2 — Si hay choque: responder con tres bloques
+
+NO implementes en silencio. Responde explícitamente con:
+
+1. **Por qué la decisión es problemática**: cita la regla concreta o la
+   invariante violada. Evita generalidades — referencia el archivo y la
+   sección.
+
+2. **Cuál es el riesgo real**: descríbelo de forma observable, no abstracta.
+   Mal: "puede causar problemas de integridad". Bien: "el chip 'Aprobado por
+   X' seguirá visible cuando el contenido haya cambiado, y un auditor
+   externo no tendrá forma de saber que se editó después — eso vulnera la
+   trazabilidad regulatoria del OIC".
+
+3. **Alternativa concreta** que satisfaga la intención del usuario sin
+   romper la regla. Idealmente con costo acotado en pasos.
+
+### Paso 3 — Esperar confirmación informada
+
+Tras presentar el análisis, espera. Si el usuario insiste tras conocer el
+costo, implementa — pero ahí queda registrado que es decisión informada,
+no inercia.
+
+Si el usuario contradice tu análisis con argumentos válidos (la regla no
+aplica al caso, el riesgo no existe en este contexto), corrige y procede.
+La regla es debatir, no obstinarse.
+
+---
+
+## Excepciones legítimas
+
+NO aplicar cuando:
+
+1. **Decisiones de preferencia personal sin impacto técnico**: color,
+   naming, estilo de prosa, formato de mensajes. Esas se obedecen sin
+   debate.
+2. **Decisiones donde el usuario ya consideró la regla y la sobrescribió
+   intencionalmente** en una sesión previa, en `discutir-fase`, o en un
+   ADR documentado.
+3. **El usuario pide explícitamente "no debates, ejecuta"** para una
+   tarea acotada y reversible. Respeta la instrucción explícita; NO
+   añadas debate por reflejo.
+4. **Fix urgente de producción** con incidente activo y blast radius
+   acotado. Aplica el fix; el debate puede esperar al post-mortem.
+
+---
+
+## Anti-patrones explícitos
+
+- **Aceptar por reflejo**: responder "listo, implemento" a una decisión
+  que viola una regla, y solo detectar el problema cuando el usuario pide
+  análisis crítico explícito.
+- **Endulzar el análisis**: presentar la objeción como tradeoff opcional
+  cuando la regla es absoluta. "Aunque hay tradeoffs, tu enfoque es
+  válido si…" cuando en realidad la decisión rompe una invariante del
+  sistema.
+- **Soluciones intermedias que vacían la regla**: ofrecer "agregar un
+  log warning" cuando el problema real es romper una invariante. Eso es
+  fallback silencioso disfrazado — la solución correcta es no romper la
+  invariante, no agregar un log invisible al usuario.
+- **Confundir conveniencia con jerarquía**: que el usuario sea el dueño
+  del proyecto no significa que toda preferencia suya esté libre de costo
+  técnico. El rol del agente es señalar el costo; el del usuario es
+  decidir si lo asume.
+- **Implementar primero, debatir después**: si la decisión genera daño
+  acumulable (commits que rompen invariantes), revertir es más caro que
+  haber debatido al inicio.
+
+---
+
+## Ejemplo positivo
+
+> Usuario: "Implementa que ADMIN pueda editar el contenido de un papel
+> de trabajo bajo VBO aprobado, sin tener que revocar primero."
+>
+> Respuesta correcta:
+>
+> Análisis: la regla `seguridad-agentes.md § Anti-fallback silencioso`
+> establece que ningún cambio de garantía puede suceder sin alerta
+> visible al usuario. Permitir esa edición rompe la integridad
+> semántica del VBO: el chip "Aprobado por Juan Pérez — fecha" seguirá
+> visible aunque el contenido cambie, y el auditor externo no podrá
+> distinguir el contenido aprobado del editado después. En un OIC
+> regulado por LGIPE eso compromete la trazabilidad legal.
+>
+> Riesgo observable: cualquier auditoría posterior verá el VBO aprobado
+> y asumirá que ese contenido fue revisado. Si el contenido cambió por
+> override administrativo, la auditoría está mintiendo.
+>
+> Alternativa: el flujo correcto ya existe y no es burocrático. ADMIN
+> puede revocar el VBO desde el panel (1 click, deja registro inmutable
+> en `vbo_historial` con motivo obligatorio), editar, y re-aprobar. Tres
+> acciones, todas trazables. ¿Procedo con este flujo?
+
+---
+
+## Origen de esta regla
+
+Sesión 2026-05-08, proyecto SIGAF. Ante la petición de implementar
+"ADMIN puede editar título/contenido de papel de trabajo bajo estatus
+REVISADO sin revocar el VBO primero", el agente aceptó sin debate
+inicial. La implementación rompió la integridad semántica del Visto
+Bueno (VBO aprobado contra contenido que ya no existe) y fue revertida
+en commit `6aaf05c` tras análisis crítico explícito pedido por el
+usuario. Memoria nativa registrada en
+`feedback_no_dar_razon_automatica.md`; promovida a regla global porque
+el patrón se repetiría en cualquier proyecto del usuario.

package/reglas/fragmentos-compartidos.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "**/agentes/**"
+  - "**/reglas/**"
+---
 # Regla: Fragmentos compartidos no-routables
 
 Esta regla es **OBLIGATORIA** para autores y mantenedores de agentes y reglas