@saulwade/swl-ses 1.4.1 → 1.4.2

package/reglas/arreglar-al-detectar.md

@@ -1,147 +1,147 @@
-# Regla: Detectar → Informar → Arreglar en el mismo turno
-
-Esta regla es OBLIGATORIA y aplica a todo trabajo que Claude ejecute en cualquier
-proyecto del usuario. Consolida cuatro feedbacks repetidos en sesiones distintas
-entre 2026-04-23 y 2026-05-03 con la misma señal: el usuario rechaza entregas
-parciales, deuda silenciosa y bypass de errores ajenos.
-
----
-
-## Principio
-
-> Cuando detectes un error, bug, inconsistencia, anomalía o problema secundario
-> durante la ejecución de cualquier trabajo, **informa al usuario brevemente Y
-> procede a resolverlo en el mismo turno**. Nunca lo dejes como pendiente, deuda
-> implícita, "ya estaba antes" ni "fuera del scope".
-
-Esta regla resume cuatro feedbacks separados que el usuario reforzó como mismo
-principio:
-
-- "No me gustan las cosas a medias" — rechazo de entregas parciales (2026-04-23).
-- "Cuando detectes errores, bugs, inconsistencias y demás informes al usuario y
-  procedas a solucionar y/o arreglar, además nunca debes dejar pendientes, ni
-  diferir" (2026-04-30).
-- "Resuelve los test que fallan, no bypass" — al detectar intento de excluir
-  tests del glob para evitar arreglarlos (2026-04-30).
-- "Si el job CI falla, hay que arreglarlo todo" — al ver tests rotos
-  presentados como "preexistentes, no críticos" (2026-05-03).
-
----
-
-## Cómo aplicar
-
-### Al detectar un problema secundario durante el trabajo principal
-
-- Reportarlo brevemente al usuario: qué se detectó, dónde, severidad.
-- Resolverlo en el mismo turno o en commit separado de la misma sesión.
-- NUNCA ofrecer "lo documento como deuda" como primera opción.
-- NUNCA usar frases como "son tests con mocks pre-existentes que ya estaban rotos",
-  "esto estaba antes", "no es del scope inmediato" para evitar el trabajo.
-
-### Al ejecutar tests, builds, lints, validadores
-
-- Si hay failures, listarlos todos y atacarlos todos.
-- No distinguir "bugs reales" vs "tests con mocks mal configurados" como excusa
-  para arreglar solo unos. Si están rotos, arreglarlos.
-- Excepción: bugs que requieran decisión arquitectural ambigua del usuario —
-  pedir esa decisión explícitamente, no diferir como "tu decisión".
-
-### Al modificar código adyacente
-
-- Si tocas líneas con problemas adyacentes (None checks faltantes, schemas
-  obsoletos, mocks inconsistentes, contadores stale, paths inválidos),
-  arreglarlos en el mismo commit o en commit separado de la misma sesión.
-
-### Al refactorizar
-
-- Si encuentras código adyacente que se quedó obsoleto por un refactor previo,
-  actualizarlo. No dejar deuda residual.
-
-### Al detectar un error ajeno al trabajo actual
-
-- NO bypassear (excluir tests del glob, comentar checks, `|| true`,
-  downgradear a warning, ignorar).
-- Resolver de raíz o, si requiere decisión, abrir explícitamente la decisión
-  con el usuario antes de bypassear.
-- El default es resolver, no esquivar.
-
-### Al presentar planes con sub-tareas
-
-- Dar primero la opción "todo completo" con esfuerzo estimado.
-- Si por capacity hay que partir el trabajo, hacerlo explícito con razón
-  concreta: "esta sesión cubre 3.1 a 3.4; la 3.5 va en commit separado por
-  X razón concreta", no por preferencia genérica.
-
-### Al recomendar diferir un patrón o feature
-
-- Redactar **simultáneamente** el ítem de deuda formal con criterio de disparo
-  verificable. La oferta "lo dejo apuntado" sin entrada formal no es aceptable.
-- Distinción de categorías:
-  - **DT (deuda técnica)** con plan de cierre.
-  - **DA (decisión arquitectural)** con trigger verificable.
-  - **OP (pendiente operacional)** con responsable.
-- "Mediano plazo / Q3 / cuando aparezca demanda" sin trigger verificable es
-  deuda silenciosa. Convertir a DA formal en mismo commit.
-- Trigger verificable significa condición observable: "≥2 clientes distintos
-  reportan", "p95 > 60s en producción documentado", "uso > N veces/mes",
-  no "cuando sea relevante" o "más adelante".
-
----
-
-## Excepciones legítimas
-
-NO aplicar la regla al pie de la letra cuando:
-
-1. **El fix es ambiguo** — varias opciones razonables sin criterio claro para
-   elegir. Presentar opciones concretas con la recomendación y esperar
-   decisión rápida.
-2. **El fix es destructivo** — `rm -rf`, `git reset --hard`, `git push --force`,
-   eliminar tablas de BD. Esos siguen requiriendo confirmación explícita por
-   separado, sin importar que el problema esté detectado.
-3. **El fix tiene blast radius alto** — modifica configuración de CI, infra
-   compartida, contratos públicos de API. Presentar plan, pedir confirmación.
-4. **El bug requiere decisión de producto** — comportamiento esperado ambiguo,
-   breaking change. Explícito al usuario y esperar.
-
-En todos los casos: presentar la opción y la recomendación, NO dejar el
-problema sin reportar.
-
----
-
-## Anti-patrones explícitos
-
-- "Lo dejo como deuda residual" — sin DT/DA formal con criterio de disparo.
-- "Esos tests ya estaban rotos antes" — usado para evitar arreglarlos.
-- "No es parte del scope inmediato" — para esquivar un fix obvio.
-- "Lo documento y tú decides" — para diferir trabajo claro al usuario.
-- "Mediano plazo" sin trigger verificable.
-- Excluir tests del glob, comentar checks, `|| true`, downgradear severidad de
-  un linter — para que el CI deje de fallar sin arreglar la causa.
-- Mover archivos a `legacy/` o `deprecated/` sin plan de eliminación con
-  criterio de disparo.
-
----
-
-## Relación con otras reglas
-
-- `seguridad-agentes.md` — sección "Anti-fallback silencioso y anti-degradación"
-  cubre el mismo principio aplicado a agentes autónomos. Esta regla lo extiende
-  al trabajo del usuario.
-- `git-workflow.md` — los commits siguen siendo atómicos; arreglar un problema
-  detectado puede requerir varios commits, no uno solo gigante.
-- `pruebas.md` — los tests rotos son violaciones a esta regla. No se mergea
-  con tests rotos (excepción: tests rotos por decisión de producto en proceso).
-
----
-
-## Origen de esta regla
-
-Consolidada el 2026-05-04 a partir de cuatro feedbacks repetidos del usuario en
-memorias nativas de Claude Code de los proyectos sigm, swl-ses y emaia
-(2026-04-23 a 2026-05-03). Antes vivía duplicada en 4 archivos de feedback
-distintos en 2 de los 3 proyectos. Promovida a regla global para eliminar
-duplicación y aplicar uniformemente a todo proyecto del usuario.
-
-Memoria nativa local correspondiente: redundante tras esta regla; mantener solo
-una mención mínima en MEMORY.md de cada proyecto si se desea preservar el rastro
-histórico, pero el contenido operativo vive aquí.
+# Regla: Detectar → Informar → Arreglar en el mismo turno
+
+Esta regla es OBLIGATORIA y aplica a todo trabajo que Claude ejecute en cualquier
+proyecto del usuario. Consolida cuatro feedbacks repetidos en sesiones distintas
+entre 2026-04-23 y 2026-05-03 con la misma señal: el usuario rechaza entregas
+parciales, deuda silenciosa y bypass de errores ajenos.
+
+---
+
+## Principio
+
+> Cuando detectes un error, bug, inconsistencia, anomalía o problema secundario
+> durante la ejecución de cualquier trabajo, **informa al usuario brevemente Y
+> procede a resolverlo en el mismo turno**. Nunca lo dejes como pendiente, deuda
+> implícita, "ya estaba antes" ni "fuera del scope".
+
+Esta regla resume cuatro feedbacks separados que el usuario reforzó como mismo
+principio:
+
+- "No me gustan las cosas a medias" — rechazo de entregas parciales (2026-04-23).
+- "Cuando detectes errores, bugs, inconsistencias y demás informes al usuario y
+  procedas a solucionar y/o arreglar, además nunca debes dejar pendientes, ni
+  diferir" (2026-04-30).
+- "Resuelve los test que fallan, no bypass" — al detectar intento de excluir
+  tests del glob para evitar arreglarlos (2026-04-30).
+- "Si el job CI falla, hay que arreglarlo todo" — al ver tests rotos
+  presentados como "preexistentes, no críticos" (2026-05-03).
+
+---
+
+## Cómo aplicar
+
+### Al detectar un problema secundario durante el trabajo principal
+
+- Reportarlo brevemente al usuario: qué se detectó, dónde, severidad.
+- Resolverlo en el mismo turno o en commit separado de la misma sesión.
+- NUNCA ofrecer "lo documento como deuda" como primera opción.
+- NUNCA usar frases como "son tests con mocks pre-existentes que ya estaban rotos",
+  "esto estaba antes", "no es del scope inmediato" para evitar el trabajo.
+
+### Al ejecutar tests, builds, lints, validadores
+
+- Si hay failures, listarlos todos y atacarlos todos.
+- No distinguir "bugs reales" vs "tests con mocks mal configurados" como excusa
+  para arreglar solo unos. Si están rotos, arreglarlos.
+- Excepción: bugs que requieran decisión arquitectural ambigua del usuario —
+  pedir esa decisión explícitamente, no diferir como "tu decisión".
+
+### Al modificar código adyacente
+
+- Si tocas líneas con problemas adyacentes (None checks faltantes, schemas
+  obsoletos, mocks inconsistentes, contadores stale, paths inválidos),
+  arreglarlos en el mismo commit o en commit separado de la misma sesión.
+
+### Al refactorizar
+
+- Si encuentras código adyacente que se quedó obsoleto por un refactor previo,
+  actualizarlo. No dejar deuda residual.
+
+### Al detectar un error ajeno al trabajo actual
+
+- NO bypassear (excluir tests del glob, comentar checks, `|| true`,
+  downgradear a warning, ignorar).
+- Resolver de raíz o, si requiere decisión, abrir explícitamente la decisión
+  con el usuario antes de bypassear.
+- El default es resolver, no esquivar.
+
+### Al presentar planes con sub-tareas
+
+- Dar primero la opción "todo completo" con esfuerzo estimado.
+- Si por capacity hay que partir el trabajo, hacerlo explícito con razón
+  concreta: "esta sesión cubre 3.1 a 3.4; la 3.5 va en commit separado por
+  X razón concreta", no por preferencia genérica.
+
+### Al recomendar diferir un patrón o feature
+
+- Redactar **simultáneamente** el ítem de deuda formal con criterio de disparo
+  verificable. La oferta "lo dejo apuntado" sin entrada formal no es aceptable.
+- Distinción de categorías:
+  - **DT (deuda técnica)** con plan de cierre.
+  - **DA (decisión arquitectural)** con trigger verificable.
+  - **OP (pendiente operacional)** con responsable.
+- "Mediano plazo / Q3 / cuando aparezca demanda" sin trigger verificable es
+  deuda silenciosa. Convertir a DA formal en mismo commit.
+- Trigger verificable significa condición observable: "≥2 clientes distintos
+  reportan", "p95 > 60s en producción documentado", "uso > N veces/mes",
+  no "cuando sea relevante" o "más adelante".
+
+---
+
+## Excepciones legítimas
+
+NO aplicar la regla al pie de la letra cuando:
+
+1. **El fix es ambiguo** — varias opciones razonables sin criterio claro para
+   elegir. Presentar opciones concretas con la recomendación y esperar
+   decisión rápida.
+2. **El fix es destructivo** — `rm -rf`, `git reset --hard`, `git push --force`,
+   eliminar tablas de BD. Esos siguen requiriendo confirmación explícita por
+   separado, sin importar que el problema esté detectado.
+3. **El fix tiene blast radius alto** — modifica configuración de CI, infra
+   compartida, contratos públicos de API. Presentar plan, pedir confirmación.
+4. **El bug requiere decisión de producto** — comportamiento esperado ambiguo,
+   breaking change. Explícito al usuario y esperar.
+
+En todos los casos: presentar la opción y la recomendación, NO dejar el
+problema sin reportar.
+
+---
+
+## Anti-patrones explícitos
+
+- "Lo dejo como deuda residual" — sin DT/DA formal con criterio de disparo.
+- "Esos tests ya estaban rotos antes" — usado para evitar arreglarlos.
+- "No es parte del scope inmediato" — para esquivar un fix obvio.
+- "Lo documento y tú decides" — para diferir trabajo claro al usuario.
+- "Mediano plazo" sin trigger verificable.
+- Excluir tests del glob, comentar checks, `|| true`, downgradear severidad de
+  un linter — para que el CI deje de fallar sin arreglar la causa.
+- Mover archivos a `legacy/` o `deprecated/` sin plan de eliminación con
+  criterio de disparo.
+
+---
+
+## Relación con otras reglas
+
+- `seguridad-agentes.md` — sección "Anti-fallback silencioso y anti-degradación"
+  cubre el mismo principio aplicado a agentes autónomos. Esta regla lo extiende
+  al trabajo del usuario.
+- `git-workflow.md` — los commits siguen siendo atómicos; arreglar un problema
+  detectado puede requerir varios commits, no uno solo gigante.
+- `pruebas.md` — los tests rotos son violaciones a esta regla. No se mergea
+  con tests rotos (excepción: tests rotos por decisión de producto en proceso).
+
+---
+
+## Origen de esta regla
+
+Consolidada el 2026-05-04 a partir de cuatro feedbacks repetidos del usuario en
+memorias nativas de Claude Code de los proyectos sigm, swl-ses y emaia
+(2026-04-23 a 2026-05-03). Antes vivía duplicada en 4 archivos de feedback
+distintos en 2 de los 3 proyectos. Promovida a regla global para eliminar
+duplicación y aplicar uniformemente a todo proyecto del usuario.
+
+Memoria nativa local correspondiente: redundante tras esta regla; mantener solo
+una mención mínima en MEMORY.md de cada proyecto si se desea preservar el rastro
+histórico, pero el contenido operativo vive aquí.

package/reglas/fragmentos-compartidos.md

@@ -1,152 +1,152 @@
-# Regla: Fragmentos compartidos no-routables
-
-Esta regla es **OBLIGATORIA** para autores y mantenedores de agentes y reglas
-del sistema SWL. Define un tercer tier entre reglas y skills: bloques de prompt
-compartidos que se incrustan literalmente en agentes/reglas para eliminar
-duplicación textual sin convertirse en componentes invocables.
-
----
-
-## El problema que resuelve
-
-Hoy cuando dos agentes necesitan repetir el mismo párrafo (protocolo HITL para
-nivelRiesgo ALTO, anti-fallback silencioso, regla de paralelización, mención
-de "aplica brevedad-output"), las opciones existentes son:
-
-| Mecanismo | Problema |
-|-----------|----------|
-| Copiar y pegar el bloque | Drift textual: una copia se actualiza, la otra no. |
-| Convertirlo en regla obligatoria | Las reglas son globales (cargadas por matchers), no se incrustan literal en un agente concreto. |
-| Convertirlo en skill | Las skills se invocan dinámicamente con `Skill("nombre")` y consumen tokens; un fragmento de 6 líneas no justifica el overhead. |
-| Convertirlo en agente | Los agentes son routables; un guard compartido no debe aparecer en la tabla de routing del orquestador. |
-
-Faltaba una capa para "texto compartido que vive en el system prompt del agente,
-sin overhead runtime ni routing". Esta regla la formaliza.
-
----
-
-## Convención
-
-### Ubicación y naming
-
-| Tipo | Ubicación | Naming |
-|------|-----------|--------|
-| Fragmento para agentes | `agentes/_*.md` | prefijo `_`, kebab-case, **sin sufijo `-swl`** |
-| Fragmento para reglas | `reglas/_fragmentos/_*.md` | prefijo `_`, kebab-case |
-
-**Ejemplos válidos**:
-- `agentes/_hitl-alto-riesgo.md`
-- `agentes/_anti-fallback-silencioso.md`
-- `agentes/_brevedad-output-ref.md`
-- `reglas/_fragmentos/_descarga-progresiva.md`
-
-**Ejemplos inválidos**:
-- `agentes/_scope-guard-swl.md` (no usar sufijo `-swl` — no es un agente)
-- `agentes/scope_guard.md` (snake_case prohibido)
-- `agentes/_ScopeGuard.md` (camelCase prohibido)
-
-### Reglas duras
-
-1. **NO routable**: el orquestador NO incluye `agentes/_*.md` en su tabla de
-   rutas. El prefijo `_` señala al loader que ese archivo es un fragmento, no
-   un agente. La validación `scripts/validar-manifest.js` rechaza si un
-   `agentes/_*.md` aparece en `manifiestos/modulos.json` como agente.
-
-2. **NO invocable**: no se carga con `Skill("...")`. No tiene frontmatter
-   `name`/`description` ni schema. Es texto puro Markdown.
-
-3. **Importación declarativa via frontmatter**: el agente que usa el fragmento
-   lo declara en su frontmatter:
-   ```yaml
-   fragmentos: [_hitl-alto-riesgo, _anti-fallback-silencioso]
-   ```
-   El campo `fragmentos` está definido en `schemas/agent-frontmatter.schema.json`.
-   El loader (al cargar el agente) lee cada fragmento referenciado y lo concatena
-   al final del system prompt.
-
-4. **Tamaño máximo 100 líneas**: si un fragmento crece más, probablemente debe
-   ser una regla obligatoria o una skill. Los fragmentos son párrafos, no
-   documentos.
-
-5. **Sin frontmatter operacional**: el archivo `_*.md` puede tener un comentario
-   YAML opcional al inicio con metadata humana (autor, agentes que lo usan), pero
-   NO tiene campos como `nivelRiesgo` o `permisosRed` — los hereda del agente
-   que lo importa.
-
-6. **Auditoría obligatoria**: cuando se crea un fragmento, el script
-   `scripts/validar-manifest.js` verifica que el fragmento es referenciado por
-   ≥2 agentes. Un fragmento usado por un solo agente no justifica su existencia
-   y debe re-incrustarse en el agente.
-
----
-
-## Cuándo crear un fragmento
-
-✅ Crear cuando:
-- El mismo bloque de ≥3 líneas aparece literalmente en ≥3 agentes.
-- El bloque es estructural (protocolo, regla operativa) — no contenido de
-  dominio variable.
-- Cambiar el bloque en el futuro debe propagarse a todos los agentes.
-
-❌ NO crear cuando:
-- El texto solo aparece en 1-2 agentes (no hay ahorro real).
-- El bloque ya existe como regla obligatoria (cargada por matcher).
-- El comportamiento se invoca dinámicamente (eso es una skill).
-- Es un párrafo de menos de 80 caracteres (no justifica el overhead de gestión).
-
----
-
-## Diferencia con reglas y skills
-
-| Capa | Cuándo carga | Cómo se usa | Ejemplo |
-|------|-------------|-------------|---------|
-| **Regla** (`reglas/X.md`) | Por matcher cuando se tocan ciertos archivos | Cargada al contexto global de la sesión | `reglas/seguridad.md` aplica a `*.py`, `auth/`, etc. |
-| **Skill** (`habilidades/X/SKILL.md`) | Cuando un agente invoca `Skill("X")` | Carga bajo demanda, contiene instrucciones operativas | `habilidades/tdd-workflow/SKILL.md` |
-| **Fragmento** (`agentes/_X.md`) | Al cargar un agente que lo declara en `fragmentos` | Se incrusta literalmente en system prompt — sin overhead runtime | `agentes/_hitl-alto-riesgo.md` |
-
-Los fragmentos son la opción más barata: cero tokens runtime adicional, máxima
-consistencia textual entre agentes que comparten un bloque.
-
----
-
-## Migración desde duplicación existente
-
-Para extraer un bloque duplicado a fragmento:
-
-1. **Identificar**: con `Grep` confirmar que el texto aparece literal en ≥3 agentes.
-2. **Crear** el archivo `agentes/_nombre.md` con el bloque en el estado más
-   reciente/completo de las copias existentes.
-3. **Reemplazar** en cada agente la duplicación por una referencia mínima:
-   ```markdown
-   <!-- fragmento: _nombre -->
-   ```
-   El loader sustituye este marcador por el contenido del fragmento al cargar.
-4. **Declarar** en el frontmatter del agente:
-   ```yaml
-   fragmentos: [_nombre]
-   ```
-5. **Verificar** con `node scripts/validar-manifest.js` que el fragmento está
-   referenciado por ≥2 agentes.
-6. **Commit atómico**: `refactor(fragmentos): extraer X a _nombre — usado en N agentes`.
-
----
-
-## Origen y referencias
-
-- Patrón inspirado en `_scope-guard.md` de Bug-Bounty-Agents
-  (https://github.com/anthropics/bug-bounty-agents) — convención `_` como
-  shared prompt block no-routable.
-- Decisión documentada en ADR-XXX (ver `.planning/adrs/`).
-- Schema: `schemas/agent-frontmatter.schema.json` campo `fragmentos`.
-
----
-
-## Checklist antes de crear un fragmento
-
-- [ ] El texto aparece literal en ≥3 agentes
-- [ ] El nombre sigue convención `_kebab-case.md` (sin sufijo `-swl`)
-- [ ] Tamaño ≤100 líneas
-- [ ] No reemplaza a una regla obligatoria existente
-- [ ] No es contenido invocable dinámicamente (eso es skill)
-- [ ] Cada agente que lo usa lo declara en `fragmentos: [...]`
-- [ ] `scripts/validar-manifest.js` no reporta errores
+# Regla: Fragmentos compartidos no-routables
+
+Esta regla es **OBLIGATORIA** para autores y mantenedores de agentes y reglas
+del sistema SWL. Define un tercer tier entre reglas y skills: bloques de prompt
+compartidos que se incrustan literalmente en agentes/reglas para eliminar
+duplicación textual sin convertirse en componentes invocables.
+
+---
+
+## El problema que resuelve
+
+Hoy cuando dos agentes necesitan repetir el mismo párrafo (protocolo HITL para
+nivelRiesgo ALTO, anti-fallback silencioso, regla de paralelización, mención
+de "aplica brevedad-output"), las opciones existentes son:
+
+| Mecanismo | Problema |
+|-----------|----------|
+| Copiar y pegar el bloque | Drift textual: una copia se actualiza, la otra no. |
+| Convertirlo en regla obligatoria | Las reglas son globales (cargadas por matchers), no se incrustan literal en un agente concreto. |
+| Convertirlo en skill | Las skills se invocan dinámicamente con `Skill("nombre")` y consumen tokens; un fragmento de 6 líneas no justifica el overhead. |
+| Convertirlo en agente | Los agentes son routables; un guard compartido no debe aparecer en la tabla de routing del orquestador. |
+
+Faltaba una capa para "texto compartido que vive en el system prompt del agente,
+sin overhead runtime ni routing". Esta regla la formaliza.
+
+---
+
+## Convención
+
+### Ubicación y naming
+
+| Tipo | Ubicación | Naming |
+|------|-----------|--------|
+| Fragmento para agentes | `agentes/_*.md` | prefijo `_`, kebab-case, **sin sufijo `-swl`** |
+| Fragmento para reglas | `reglas/_fragmentos/_*.md` | prefijo `_`, kebab-case |
+
+**Ejemplos válidos**:
+- `agentes/_hitl-alto-riesgo.md`
+- `agentes/_anti-fallback-silencioso.md`
+- `agentes/_brevedad-output-ref.md`
+- `reglas/_fragmentos/_descarga-progresiva.md`
+
+**Ejemplos inválidos**:
+- `agentes/_scope-guard-swl.md` (no usar sufijo `-swl` — no es un agente)
+- `agentes/scope_guard.md` (snake_case prohibido)
+- `agentes/_ScopeGuard.md` (camelCase prohibido)
+
+### Reglas duras
+
+1. **NO routable**: el orquestador NO incluye `agentes/_*.md` en su tabla de
+   rutas. El prefijo `_` señala al loader que ese archivo es un fragmento, no
+   un agente. La validación `scripts/validar-manifest.js` rechaza si un
+   `agentes/_*.md` aparece en `manifiestos/modulos.json` como agente.
+
+2. **NO invocable**: no se carga con `Skill("...")`. No tiene frontmatter
+   `name`/`description` ni schema. Es texto puro Markdown.
+
+3. **Importación declarativa via frontmatter**: el agente que usa el fragmento
+   lo declara en su frontmatter:
+   ```yaml
+   fragmentos: [_hitl-alto-riesgo, _anti-fallback-silencioso]
+   ```
+   El campo `fragmentos` está definido en `schemas/agent-frontmatter.schema.json`.
+   El loader (al cargar el agente) lee cada fragmento referenciado y lo concatena
+   al final del system prompt.
+
+4. **Tamaño máximo 100 líneas**: si un fragmento crece más, probablemente debe
+   ser una regla obligatoria o una skill. Los fragmentos son párrafos, no
+   documentos.
+
+5. **Sin frontmatter operacional**: el archivo `_*.md` puede tener un comentario
+   YAML opcional al inicio con metadata humana (autor, agentes que lo usan), pero
+   NO tiene campos como `nivelRiesgo` o `permisosRed` — los hereda del agente
+   que lo importa.
+
+6. **Auditoría obligatoria**: cuando se crea un fragmento, el script
+   `scripts/validar-manifest.js` verifica que el fragmento es referenciado por
+   ≥2 agentes. Un fragmento usado por un solo agente no justifica su existencia
+   y debe re-incrustarse en el agente.
+
+---
+
+## Cuándo crear un fragmento
+
+✅ Crear cuando:
+- El mismo bloque de ≥3 líneas aparece literalmente en ≥3 agentes.
+- El bloque es estructural (protocolo, regla operativa) — no contenido de
+  dominio variable.
+- Cambiar el bloque en el futuro debe propagarse a todos los agentes.
+
+❌ NO crear cuando:
+- El texto solo aparece en 1-2 agentes (no hay ahorro real).
+- El bloque ya existe como regla obligatoria (cargada por matcher).
+- El comportamiento se invoca dinámicamente (eso es una skill).
+- Es un párrafo de menos de 80 caracteres (no justifica el overhead de gestión).
+
+---
+
+## Diferencia con reglas y skills
+
+| Capa | Cuándo carga | Cómo se usa | Ejemplo |
+|------|-------------|-------------|---------|
+| **Regla** (`reglas/X.md`) | Por matcher cuando se tocan ciertos archivos | Cargada al contexto global de la sesión | `reglas/seguridad.md` aplica a `*.py`, `auth/`, etc. |
+| **Skill** (`habilidades/X/SKILL.md`) | Cuando un agente invoca `Skill("X")` | Carga bajo demanda, contiene instrucciones operativas | `habilidades/tdd-workflow/SKILL.md` |
+| **Fragmento** (`agentes/_X.md`) | Al cargar un agente que lo declara en `fragmentos` | Se incrusta literalmente en system prompt — sin overhead runtime | `agentes/_hitl-alto-riesgo.md` |
+
+Los fragmentos son la opción más barata: cero tokens runtime adicional, máxima
+consistencia textual entre agentes que comparten un bloque.
+
+---
+
+## Migración desde duplicación existente
+
+Para extraer un bloque duplicado a fragmento:
+
+1. **Identificar**: con `Grep` confirmar que el texto aparece literal en ≥3 agentes.
+2. **Crear** el archivo `agentes/_nombre.md` con el bloque en el estado más
+   reciente/completo de las copias existentes.
+3. **Reemplazar** en cada agente la duplicación por una referencia mínima:
+   ```markdown
+   <!-- fragmento: _nombre -->
+   ```
+   El loader sustituye este marcador por el contenido del fragmento al cargar.
+4. **Declarar** en el frontmatter del agente:
+   ```yaml
+   fragmentos: [_nombre]
+   ```
+5. **Verificar** con `node scripts/validar-manifest.js` que el fragmento está
+   referenciado por ≥2 agentes.
+6. **Commit atómico**: `refactor(fragmentos): extraer X a _nombre — usado en N agentes`.
+
+---
+
+## Origen y referencias
+
+- Patrón inspirado en `_scope-guard.md` de Bug-Bounty-Agents
+  (https://github.com/anthropics/bug-bounty-agents) — convención `_` como
+  shared prompt block no-routable.
+- Decisión documentada en ADR-XXX (ver `.planning/adrs/`).
+- Schema: `schemas/agent-frontmatter.schema.json` campo `fragmentos`.
+
+---
+
+## Checklist antes de crear un fragmento
+
+- [ ] El texto aparece literal en ≥3 agentes
+- [ ] El nombre sigue convención `_kebab-case.md` (sin sufijo `-swl`)
+- [ ] Tamaño ≤100 líneas
+- [ ] No reemplaza a una regla obligatoria existente
+- [ ] No es contenido invocable dinámicamente (eso es skill)
+- [ ] Cada agente que lo usa lo declara en `fragmentos: [...]`
+- [ ] `scripts/validar-manifest.js` no reporta errores