@saulwade/swl-ses 2.3.0 → 2.4.1

package/reglas/intent-engineering.md

@@ -1,218 +1,218 @@
----
-paths:
-  - "**/agentes/*.md"
----
-# Regla: Intent Engineering para agentes ALTO riesgo
-
-Esta regla es **OBLIGATORIA** y aplica al crear, modificar o promover agentes
-del sistema SWL cuyo `nivelRiesgo` sea `ALTO`. Implementa el framework
-"Intent Engineering" de 8 partes de Pawel Huryn (*Lead Agents Like Humans*,
-Product Compass, 2026-05).
-
----
-
-## Principio
-
-> Un agente con autonomía elevada que opera sin intent specification explícito
-> falla silenciosamente por instrucciones ambiguas, deriva de scope o pérdida
-> de health metrics. Los agentes ALTO riesgo del sistema SWL DEBEN declarar
-> las 8 partes del framework de forma verificable (frontmatter + fragmento),
-> no implícita.
-
-Huryn lo resume:
-
-> "Agents don't fail because the model is weak. They fail because intent is
-> incomplete. Objectives are vague. Outcomes are implicit. Trade-offs are
-> unstated. Constraints are treated as suggestions. Autonomy is granted
-> without understanding risk." (Lead Agents Like Humans, línea 56)
-
-SWL adopta el framework parcialmente: las partes 5 (Org Context) y 3
-(Desired Outcomes) viven en `CLAUDE.md` y `PLAN.md` respectivamente, no en
-cada agente. Las otras 6 son responsabilidad del autor del agente.
-
----
-
-## Cuándo aplicar
-
-OBLIGATORIO al:
-
-- Crear un agente nuevo `nivelRiesgo: ALTO`.
-- Modificar el frontmatter de un agente `nivelRiesgo: ALTO` existente.
-- Promover un agente de `MEDIO` o `BAJO` a `ALTO`.
-- Auditar agentes con `/swl:revisar` cuando se detecta deriva de scope.
-
-NO aplicar al:
-
-- Agentes `BAJO` o `MEDIO` riesgo (los campos son opcionales para ellos).
-- Cambios cosméticos al cuerpo markdown del agente sin tocar frontmatter.
-- Skills, hooks, comandos (la regla aplica solo a agentes).
-
----
-
-## Lo que DEBE declarar un agente ALTO
-
-### En el frontmatter YAML
-
-```yaml
-nivelRiesgo: ALTO            # Parte 7 — Autonomy Boundaries
-maxTurnos: <int>             # Parte 8 — Stop Rules (cap iteraciones)
-strategy: "<1-3 lineas>"     # Parte 1 — Strategy (max 500 chars)
-healthMetrics:               # Parte 4 — qué NO debe degradar
-  - "<invariante 1>"
-  - "<invariante 2>"
-steering:                    # Parte 6 — prompt-level constraints
-  - "<guía de comportamiento o @reglas/X.md>"
-hardGuardrails:              # Parte 6 — orchestration-level constraints
-  - "<restricción enforced por hook/schema o @reglas/X.md>"
-fragmentos:
-  - _intent-spec             # Importa el bloque compartido al system prompt
-```
-
-### En el cuerpo markdown
-
-NO requerido pero recomendado: agregar sección breve "Health Metrics" o
-"Constraints" si el rol del agente justifica explicación adicional.
-
----
-
-## Criterios de calidad por campo
-
-### `strategy:`
-
-- 1-3 líneas, máximo 500 caracteres.
-- Nombra el tradeoff que el agente prioriza.
-- NO es boilerplate genérico ("código limpio", "buenas prácticas").
-- Hereda del proyecto cuando aplica; declara explícito cuando el rol impone
-  tradeoffs propios.
-
-**Ejemplo válido** (`migrador-swl`):
-```yaml
-strategy: >
-  Preservar integridad de datos por encima de velocidad de migración.
-  Expand-contract obligatorio sobre cambios destructivos. Rollback siempre
-  viable. Sin downtime es preferible a migración rápida.
-```
-
-**Ejemplo inválido**:
-```yaml
-strategy: "Migrar datos de forma segura."   # boilerplate genérico
-```
-
-### `healthMetrics:`
-
-- Lista de invariantes blandas que el agente protege mientras trabaja.
-- Distintas de `outcomes`: outcomes se persiguen, health metrics se
-  protegen.
-- Sin métrica = sin protección. Agentes ALTO sin health metrics violan
-  Goodhart's Law por construcción.
-- Pueden ser cualitativas si no hay telemetría que las mida live ("sin
-  warnings nuevos de ORM").
-
-### `steering:`
-
-- Soft constraints. El agente las lee como guía.
-- Acepta texto inline o referencia a regla global (`@reglas/X.md`).
-- NO duplicar contenido de `@reglas/X.md` — referenciar evita drift.
-
-### `hardGuardrails:`
-
-- Hard constraints aplicadas por arquitectura (hooks, schemas, sandbox).
-- Cada item DEBE referenciar el mecanismo que enforza:
-  - `@reglas/seguridad-agentes.md § Privilegio mínimo` (regla global)
-  - `@hooks/proteccion-rutas.js` (hook bloqueante)
-  - `@schemas/agent-frontmatter.schema.json#properties.tools` (validación)
-- Si la restricción no tiene mecanismo de enforcement, NO es hard
-  guardrail — es steering.
-
----
-
-## Excepciones legítimas
-
-NO aplica la regla cuando:
-
-1. **El agente acaba de bajar de ALTO a MEDIO/BAJO**: si en una revisión se
-   determina que un agente puede operar con menos privilegio, primero baja
-   el `nivelRiesgo`, luego los campos se vuelven opcionales.
-
-2. **El agente está en proceso de deprecación**: agentes marcados
-   `evolvable: false` con plan de retiro documentado en ADR pueden quedar
-   sin las 8 partes hasta su retiro. Documentar excepción en commit.
-
-3. **Refactor cosmético reversible**: cambios al cuerpo markdown que no
-   modifican `nivelRiesgo:` ni los 4 campos nuevos no disparan la regla.
-
----
-
-## Cómo verificar conformidad
-
-### Manualmente
-
-Para auditar un agente ALTO:
-
-```bash
-node -e "
-const a = require('js-yaml').load(require('fs').readFileSync(process.argv[1], 'utf-8').match(/^---\n([\s\S]+?)\n---/)[1]);
-if (a.nivelRiesgo !== 'ALTO') { console.log('NO-ALTO'); return; }
-const faltan = ['strategy','healthMetrics','steering','hardGuardrails'].filter(k => !a[k]);
-if (faltan.length) console.error('FALTAN:', faltan.join(','));
-else console.log('OK');
-" agentes/X-swl.md
-```
-
-### Automáticamente
-
-Hook `hooks/validar-intent-spec.js` (creado en F3) ejecuta esta validación
-en PostToolUse sobre `Write|Edit` de `agentes/*.md`. Modo inicial:
-`blocking: false` (warn-only). Promoción a `blocking: true` tras 2 semanas
-estables sin falsos positivos, documentada en ADR-0027.
-
----
-
-## Anti-patrones
-
-- **Declarar `steering` algo que requiere enforcement**: "no eliminar
-  archivos" sin hook que lo prevenga. Si importa, va en `hardGuardrails`
-  con apoyo arquitectural.
-- **Copiar `@reglas/X.md` completa en `hardGuardrails`**: referenciar, no
-  duplicar. La regla evoluciona; la copia se queda atrás.
-- **Health metrics como outcomes negados**: "latencia < 200ms" es outcome;
-  "no degradar latencia mientras trabajas" es health metric.
-- **Strategy demasiado vaga**: si la strategy aplica a cualquier agente,
-  no es strategy de este agente. Borrar o especificar.
-- **Promover a ALTO sin declarar las 6 partes**: violación directa de
-  esta regla; el hook F3 (cuando blocking=true) lo previene.
-
----
-
-## Relación con otras reglas
-
-- `reglas/seguridad-agentes.md § Privilegio mínimo` — los campos nuevos NO
-  escalan privilegios; son metadata declarativa.
-- `reglas/fragmentos-compartidos.md` — el `_intent-spec` importado es un
-  fragmento legítimo.
-- `reglas/skills-estandar.md` — los skills cargables (`proceso-intent-engineering`)
-  son la versión on-demand del fragmento.
-- `reglas/registro-componentes-nuevos.md` — al agregar agente nuevo ALTO,
-  registrar en manifiestos sigue siendo obligatorio.
-
----
-
-## Cargar para aprender el framework
-
-```
-Skill("proceso-intent-engineering")
-```
-
-El skill explica cada parte con ejemplos, mapea Huryn (4 tiers) a SWL (3
-tiers), enumera anti-patrones y entrega tabla de referencia rápida.
-
----
-
-## Origen
-
-Regla creada el 2026-05-18 como parte de Opción B (ver ADR-0025). Cubre el
-gap detectado en análisis del artículo Huryn: SWL cubría 5/8 partes pero
-no enforzaba sistemáticamente las 3 restantes (Strategy, Health Metrics,
-Constraints distinguidas). La regla aplica solo a agentes ALTO porque
-costos de declaración no compensan en agentes BAJO/MEDIO (los 6 agentes
-del CONTEXTO original que eran BAJO/MEDIO se dejan opcionales).
+---
+paths:
+  - "**/agentes/*.md"
+---
+# Regla: Intent Engineering para agentes ALTO riesgo
+
+Esta regla es **OBLIGATORIA** y aplica al crear, modificar o promover agentes
+del sistema SWL cuyo `nivelRiesgo` sea `ALTO`. Implementa el framework
+"Intent Engineering" de 8 partes de Pawel Huryn (*Lead Agents Like Humans*,
+Product Compass, 2026-05).
+
+---
+
+## Principio
+
+> Un agente con autonomía elevada que opera sin intent specification explícito
+> falla silenciosamente por instrucciones ambiguas, deriva de scope o pérdida
+> de health metrics. Los agentes ALTO riesgo del sistema SWL DEBEN declarar
+> las 8 partes del framework de forma verificable (frontmatter + fragmento),
+> no implícita.
+
+Huryn lo resume:
+
+> "Agents don't fail because the model is weak. They fail because intent is
+> incomplete. Objectives are vague. Outcomes are implicit. Trade-offs are
+> unstated. Constraints are treated as suggestions. Autonomy is granted
+> without understanding risk." (Lead Agents Like Humans, línea 56)
+
+SWL adopta el framework parcialmente: las partes 5 (Org Context) y 3
+(Desired Outcomes) viven en `CLAUDE.md` y `PLAN.md` respectivamente, no en
+cada agente. Las otras 6 son responsabilidad del autor del agente.
+
+---
+
+## Cuándo aplicar
+
+OBLIGATORIO al:
+
+- Crear un agente nuevo `nivelRiesgo: ALTO`.
+- Modificar el frontmatter de un agente `nivelRiesgo: ALTO` existente.
+- Promover un agente de `MEDIO` o `BAJO` a `ALTO`.
+- Auditar agentes con `/swl:revisar` cuando se detecta deriva de scope.
+
+NO aplicar al:
+
+- Agentes `BAJO` o `MEDIO` riesgo (los campos son opcionales para ellos).
+- Cambios cosméticos al cuerpo markdown del agente sin tocar frontmatter.
+- Skills, hooks, comandos (la regla aplica solo a agentes).
+
+---
+
+## Lo que DEBE declarar un agente ALTO
+
+### En el frontmatter YAML
+
+```yaml
+nivelRiesgo: ALTO            # Parte 7 — Autonomy Boundaries
+maxTurnos: <int>             # Parte 8 — Stop Rules (cap iteraciones)
+strategy: "<1-3 lineas>"     # Parte 1 — Strategy (max 500 chars)
+healthMetrics:               # Parte 4 — qué NO debe degradar
+  - "<invariante 1>"
+  - "<invariante 2>"
+steering:                    # Parte 6 — prompt-level constraints
+  - "<guía de comportamiento o @reglas/X.md>"
+hardGuardrails:              # Parte 6 — orchestration-level constraints
+  - "<restricción enforced por hook/schema o @reglas/X.md>"
+fragmentos:
+  - _intent-spec             # Importa el bloque compartido al system prompt
+```
+
+### En el cuerpo markdown
+
+NO requerido pero recomendado: agregar sección breve "Health Metrics" o
+"Constraints" si el rol del agente justifica explicación adicional.
+
+---
+
+## Criterios de calidad por campo
+
+### `strategy:`
+
+- 1-3 líneas, máximo 500 caracteres.
+- Nombra el tradeoff que el agente prioriza.
+- NO es boilerplate genérico ("código limpio", "buenas prácticas").
+- Hereda del proyecto cuando aplica; declara explícito cuando el rol impone
+  tradeoffs propios.
+
+**Ejemplo válido** (`migrador-swl`):
+```yaml
+strategy: >
+  Preservar integridad de datos por encima de velocidad de migración.
+  Expand-contract obligatorio sobre cambios destructivos. Rollback siempre
+  viable. Sin downtime es preferible a migración rápida.
+```
+
+**Ejemplo inválido**:
+```yaml
+strategy: "Migrar datos de forma segura."   # boilerplate genérico
+```
+
+### `healthMetrics:`
+
+- Lista de invariantes blandas que el agente protege mientras trabaja.
+- Distintas de `outcomes`: outcomes se persiguen, health metrics se
+  protegen.
+- Sin métrica = sin protección. Agentes ALTO sin health metrics violan
+  Goodhart's Law por construcción.
+- Pueden ser cualitativas si no hay telemetría que las mida live ("sin
+  warnings nuevos de ORM").
+
+### `steering:`
+
+- Soft constraints. El agente las lee como guía.
+- Acepta texto inline o referencia a regla global (`@reglas/X.md`).
+- NO duplicar contenido de `@reglas/X.md` — referenciar evita drift.
+
+### `hardGuardrails:`
+
+- Hard constraints aplicadas por arquitectura (hooks, schemas, sandbox).
+- Cada item DEBE referenciar el mecanismo que enforza:
+  - `@reglas/seguridad-agentes.md § Privilegio mínimo` (regla global)
+  - `@hooks/proteccion-rutas.js` (hook bloqueante)
+  - `@schemas/agent-frontmatter.schema.json#properties.tools` (validación)
+- Si la restricción no tiene mecanismo de enforcement, NO es hard
+  guardrail — es steering.
+
+---
+
+## Excepciones legítimas
+
+NO aplica la regla cuando:
+
+1. **El agente acaba de bajar de ALTO a MEDIO/BAJO**: si en una revisión se
+   determina que un agente puede operar con menos privilegio, primero baja
+   el `nivelRiesgo`, luego los campos se vuelven opcionales.
+
+2. **El agente está en proceso de deprecación**: agentes marcados
+   `evolvable: false` con plan de retiro documentado en ADR pueden quedar
+   sin las 8 partes hasta su retiro. Documentar excepción en commit.
+
+3. **Refactor cosmético reversible**: cambios al cuerpo markdown que no
+   modifican `nivelRiesgo:` ni los 4 campos nuevos no disparan la regla.
+
+---
+
+## Cómo verificar conformidad
+
+### Manualmente
+
+Para auditar un agente ALTO:
+
+```bash
+node -e "
+const a = require('js-yaml').load(require('fs').readFileSync(process.argv[1], 'utf-8').match(/^---\n([\s\S]+?)\n---/)[1]);
+if (a.nivelRiesgo !== 'ALTO') { console.log('NO-ALTO'); return; }
+const faltan = ['strategy','healthMetrics','steering','hardGuardrails'].filter(k => !a[k]);
+if (faltan.length) console.error('FALTAN:', faltan.join(','));
+else console.log('OK');
+" agentes/X-swl.md
+```
+
+### Automáticamente
+
+Hook `hooks/validar-intent-spec.js` (creado en F3) ejecuta esta validación
+en PostToolUse sobre `Write|Edit` de `agentes/*.md`. Modo inicial:
+`blocking: false` (warn-only). Promoción a `blocking: true` tras 2 semanas
+estables sin falsos positivos, documentada en ADR-0027.
+
+---
+
+## Anti-patrones
+
+- **Declarar `steering` algo que requiere enforcement**: "no eliminar
+  archivos" sin hook que lo prevenga. Si importa, va en `hardGuardrails`
+  con apoyo arquitectural.
+- **Copiar `@reglas/X.md` completa en `hardGuardrails`**: referenciar, no
+  duplicar. La regla evoluciona; la copia se queda atrás.
+- **Health metrics como outcomes negados**: "latencia < 200ms" es outcome;
+  "no degradar latencia mientras trabajas" es health metric.
+- **Strategy demasiado vaga**: si la strategy aplica a cualquier agente,
+  no es strategy de este agente. Borrar o especificar.
+- **Promover a ALTO sin declarar las 6 partes**: violación directa de
+  esta regla; el hook F3 (cuando blocking=true) lo previene.
+
+---
+
+## Relación con otras reglas
+
+- `reglas/seguridad-agentes.md § Privilegio mínimo` — los campos nuevos NO
+  escalan privilegios; son metadata declarativa.
+- `reglas/fragmentos-compartidos.md` — el `_intent-spec` importado es un
+  fragmento legítimo.
+- `reglas/skills-estandar.md` — los skills cargables (`proceso-intent-engineering`)
+  son la versión on-demand del fragmento.
+- `reglas/registro-componentes-nuevos.md` — al agregar agente nuevo ALTO,
+  registrar en manifiestos sigue siendo obligatorio.
+
+---
+
+## Cargar para aprender el framework
+
+```
+Skill("proceso-intent-engineering")
+```
+
+El skill explica cada parte con ejemplos, mapea Huryn (4 tiers) a SWL (3
+tiers), enumera anti-patrones y entrega tabla de referencia rápida.
+
+---
+
+## Origen
+
+Regla creada el 2026-05-18 como parte de Opción B (ver ADR-0025). Cubre el
+gap detectado en análisis del artículo Huryn: SWL cubría 5/8 partes pero
+no enforzaba sistemáticamente las 3 restantes (Strategy, Health Metrics,
+Constraints distinguidas). La regla aplica solo a agentes ALTO porque
+costos de declaración no compensan en agentes BAJO/MEDIO (los 6 agentes
+del CONTEXTO original que eran BAJO/MEDIO se dejan opcionales).

package/reglas/markitdown.md

@@ -1,11 +1,11 @@
----
-paths:
-  - "**/*.docx"
-  - "**/*.xlsx"
-  - "**/*.xls"
-  - "**/*.pptx"
-  - "**/*.ipynb"
----
+---
+paths:
+  - "**/*.docx"
+  - "**/*.xlsx"
+  - "**/*.xls"
+  - "**/*.pptx"
+  - "**/*.ipynb"
+---
 # Regla: Lectura de documentos Office y Jupyter con MarkItDown
 
 Esta regla aplica cuando un agente necesita **leer el contenido** de un archivo