@saulwade/swl-ses 1.3.4 → 1.3.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/CLAUDE.md +2 -2
  2. package/README.md +34 -34
  3. package/bin/swl-mcp-server.js +187 -187
  4. package/bin/swl-ses.js +4 -62
  5. package/comandos/swl/.evolved.json +22 -22
  6. package/comandos/swl/adoptar-proyecto.md +207 -207
  7. package/comandos/swl/contribuir.md +233 -233
  8. package/habilidades/backend-production-resilience/SKILL.md +288 -288
  9. package/habilidades/benchmark-memoria/SKILL.md +186 -186
  10. package/habilidades/diagrama-arquitectura/assets/template.html +276 -276
  11. package/habilidades/doubt-driven-review/SKILL.md +171 -171
  12. package/habilidades/doubt-driven-review/recursos/EXAMPLES.md +130 -130
  13. package/habilidades/eval-framework/SKILL.md +212 -212
  14. package/habilidades/extractor-de-aprendizajes/SKILL.md +321 -321
  15. package/habilidades/harness-claude-code/SKILL.md +299 -299
  16. package/habilidades/infra-github-actions/SKILL.md +166 -166
  17. package/habilidades/legacy-code-rescue/SKILL.md +267 -267
  18. package/habilidades/manejo-errores/.evolved.json +8 -8
  19. package/habilidades/meta-skills-estandar/recursos/convencion-examples.md +93 -93
  20. package/habilidades/meta-skills-estandar/recursos/skills-as-agents.md +163 -163
  21. package/habilidades/patrones-python/SKILL.md +229 -229
  22. package/habilidades/patrones-python/recursos/patrones-avanzados.md +469 -469
  23. package/habilidades/planear-fase/SKILL.md +319 -319
  24. package/habilidades/release-semver/.evolved.json +8 -8
  25. package/habilidades/swl-claudemd/SKILL.md +220 -220
  26. package/habilidades/testing-python/SKILL.md +340 -340
  27. package/hooks/claudemd-bloat-detector.js +161 -161
  28. package/hooks/extraccion-aprendizajes.js +19 -12
  29. package/hooks/lib/agent-routing.js +107 -107
  30. package/hooks/lib/auto-consolidator.js +335 -335
  31. package/hooks/lib/error-classifier.js +308 -308
  32. package/hooks/lib/merkle-audit.js +96 -96
  33. package/hooks/lib/provenance-tracker.js +191 -191
  34. package/hooks/lib/rate-limit-tracker.js +253 -253
  35. package/hooks/lib/resource-quota.js +122 -122
  36. package/hooks/lib/retry-jitter.js +165 -165
  37. package/hooks/lib/skill-auditor.js +588 -588
  38. package/hooks/lib/sync-status.js +228 -228
  39. package/hooks/lib/taint-tracker.js +107 -107
  40. package/hooks/lib/text-similarity.js +241 -241
  41. package/hooks/lib/toon-compressor.js +245 -245
  42. package/hooks/registro-turnos.js +209 -209
  43. package/hooks/sugerir-regenerar-inventario.js +170 -170
  44. package/hooks/validar-formato-post-subagente.js +140 -140
  45. package/hooks/validar-memoria-hook.js +218 -218
  46. package/instintos/prompt-appendices.yaml +57 -57
  47. package/manifiestos/agent-output-schemas.json +57 -57
  48. package/manifiestos/skills-lock.json +1093 -1093
  49. package/package.json +1 -1
  50. package/plantillas/auditor-veto-template.md +105 -105
  51. package/plantillas/github-workflows/README.md +47 -47
  52. package/plantillas/github-workflows/release-please.yml +44 -44
  53. package/plantillas/github-workflows/swl-ci.yml +107 -107
  54. package/plantillas/github-workflows/swl-security.yml +51 -51
  55. package/plugin.json +1 -1
  56. package/reglas/analisis-previo-tareas-grandes.md +172 -172
  57. package/reglas/arreglar-al-detectar.md +147 -147
  58. package/reglas/fragmentos-compartidos.md +152 -152
  59. package/reglas/harness-claude-code.md +213 -213
  60. package/reglas/usar-context7.md +226 -226
  61. package/schemas/diary-entry.schema.json +80 -80
  62. package/scripts/benchmark-memoria.js +167 -167
  63. package/scripts/comandos/info.js +1 -1
  64. package/scripts/configurar-branch-protection.js +418 -418
  65. package/scripts/detectar-aprendizajes-duplicados.js +151 -151
  66. package/scripts/doctor.js +77 -3
  67. package/scripts/field-report.js +199 -199
  68. package/scripts/generar-checklists-consolidados.js +273 -273
  69. package/scripts/generar-inventario.js +420 -420
  70. package/scripts/generar-matriz-lenguajes.js +271 -271
  71. package/scripts/inicializar.js +2 -2
  72. package/scripts/instalador.js +40 -3
  73. package/scripts/instalar-git-hook.js +2 -2
  74. package/scripts/lib/artefactos-python.js +43 -43
  75. package/scripts/lib/benchmark-metrics.js +160 -160
  76. package/scripts/lib/budget-enforcer.js +252 -252
  77. package/scripts/lib/configurar-ci.js +380 -380
  78. package/scripts/lib/contadores-inventario.js +217 -217
  79. package/scripts/lib/detectar-stack-detallado.js +307 -307
  80. package/scripts/lib/diary-entry.js +234 -234
  81. package/scripts/lib/eval-metrics-store.js +218 -218
  82. package/scripts/lib/eval-quality.js +171 -171
  83. package/scripts/lib/eval-schemas.js +144 -144
  84. package/scripts/lib/eval-self-correct.js +106 -106
  85. package/scripts/lib/eval-validator.js +185 -185
  86. package/scripts/lib/gitignore-manifest.js +1 -1
  87. package/scripts/lib/jaccard-similarity.js +98 -98
  88. package/scripts/lib/longmemeval-runner.js +125 -125
  89. package/scripts/lib/npm-version.js +261 -261
  90. package/scripts/lib/paquetes-conocidos.js +50 -50
  91. package/scripts/lib/parsear-opciones.js +136 -0
  92. package/scripts/lib/prompt-builder.js +264 -264
  93. package/scripts/lib/rrf-fusion.js +175 -175
  94. package/scripts/lib/scoring-instintos.js +277 -277
  95. package/scripts/lib/semantic-search.js +252 -252
  96. package/scripts/lib/transformadores/claude.js +200 -200
  97. package/scripts/lib/transformadores/codex.js +1 -1
  98. package/scripts/lib/transformadores/copilot.js +1 -1
  99. package/scripts/lib/transformadores/gemini.js +1 -1
  100. package/scripts/lib/transformadores/opencode.js +1 -1
  101. package/scripts/limpiar-artefactos-python.js +131 -131
  102. package/scripts/mcp-server/README.md +128 -128
  103. package/scripts/mcp-server/handlers.js +206 -206
  104. package/scripts/migrar-csv-a-array.js +168 -168
  105. package/scripts/migrar-fase-dominio.js +201 -201
  106. package/scripts/publicar.js +511 -511
  107. package/scripts/run-eval.js +141 -141
  108. package/scripts/validar-manifest.js +195 -195
  109. package/scripts/validar-userland-vacio.js +110 -110
  110. package/scripts/verificar-release.js +5 -1
@@ -1,200 +1,200 @@
1
- 'use strict';
2
-
3
- const TransformadorBase = require('./base');
4
- const { detectarStackDetallado } = require('../detectar-stack-detallado');
5
-
6
- class TransformadorClaude extends TransformadorBase {
7
- transformarAgente(contenidoMd, metadatos) {
8
- // Pass-through: Claude soporta el formato SWL directamente
9
- return {
10
- contenido: contenidoMd,
11
- rutaRelativa: `agents/${metadatos.nombreArchivo}`,
12
- };
13
- }
14
-
15
- transformarSkill(dirSkill, metadatos) {
16
- // Pass-through: copiar directorio completo
17
- return {
18
- tipo: 'directorio',
19
- rutaRelativa: `skills/${metadatos.nombreDirectorio}`,
20
- };
21
- }
22
-
23
- transformarRegla(contenidoMd, metadatos) {
24
- return {
25
- contenido: contenidoMd,
26
- rutaRelativa: `rules/${metadatos.nombreArchivo}`,
27
- };
28
- }
29
-
30
- transformarComando(contenidoMd, metadatos) {
31
- return {
32
- contenido: contenidoMd,
33
- rutaRelativa: `commands/swl/${metadatos.nombreArchivo}`,
34
- };
35
- }
36
-
37
- /**
38
- * Genera el bloque SWL para insertar en el CLAUDE.md del proyecto destino.
39
- *
40
- * A diferencia de los otros transformadores (codex/gemini/copilot/opencode)
41
- * que generan el archivo completo de instrucciones desde cero, Claude usa
42
- * un CLAUDE.md que el usuario mantiene y que puede tener contenido propio
43
- * (reglas del proyecto, convenciones, notas). Por eso:
44
- *
45
- * - El contenido devuelto es un BLOQUE (no archivo completo)
46
- * - Se devuelve `merge: { tipo: 'marcadores', ... }` para indicar al
47
- * caller que debe usar `append-con-marcadores` en lugar de writeFileSync
48
- * - Los marcadores `<!-- SWL-BEGIN vX.Y.Z -->` / `<!-- SWL-END -->`
49
- * permiten que la siguiente actualización reemplace solo este bloque
50
- * sin tocar el contenido del usuario
51
- *
52
- * Aplicación de ADR-0016 (best practices Anthropic "The CLAUDE.md file"):
53
- * - Detecta stack del proyecto destino (lenguaje, framework, ORM,
54
- * package manager, comandos disponibles)
55
- * - Genera secciones canónicas: Stack / Comandos del proyecto / Sistema SWL
56
- * - Documenta jerarquía project / user-level (`~/.claude/CLAUDE.md`)
57
- * - Documenta patrón "ask Claude to save to memory" del video oficial
58
- */
59
- generarArchivoInstrucciones(contexto) {
60
- const fecha = new Date().toISOString().split('T')[0];
61
- const stack = contexto.dirProyecto
62
- ? this._detectarStackSeguro(contexto.dirProyecto)
63
- : null;
64
-
65
- const lineas = [
66
- `> Gestionado por swl-ses v${contexto.version} — no editar entre estos marcadores.`,
67
- `> Regenerado en ${fecha} con perfil \`${contexto.perfil || 'default'}\`.`,
68
- `> Para excluir este bloque en futuras actualizaciones: \`npx swl-ses@latest install --no-claudemd\`.`,
69
- '',
70
- ];
71
-
72
- // ─── Stack del proyecto detectado (best practice Anthropic #2) ─────────
73
- if (stack && stack.detectado) {
74
- lineas.push('## Stack del proyecto');
75
- lineas.push('');
76
- const partes = [];
77
- if (stack.lenguajePrincipal) {
78
- partes.push(`**Lenguaje**: ${stack.lenguajePrincipal.lenguaje}` +
79
- (stack.lenguajePrincipal.runtime ? ` (${stack.lenguajePrincipal.runtime})` : ''));
80
- }
81
- if (stack.framework) partes.push(`**Framework**: ${stack.framework}`);
82
- if (stack.orm) partes.push(`**ORM/BD**: ${stack.orm}`);
83
- if (stack.packageManager) partes.push(`**Package manager**: ${stack.packageManager}`);
84
- lineas.push('- ' + partes.join('\n- '));
85
- lineas.push('');
86
- }
87
-
88
- // ─── Comandos del proyecto (best practice Anthropic #3) ────────────────
89
- if (stack && stack.comandos && stack.comandos.length > 0) {
90
- lineas.push('## Comandos del proyecto');
91
- lineas.push('');
92
- lineas.push('| Comando | Propósito |');
93
- lineas.push('|---------|-----------|');
94
- for (const c of stack.comandos) {
95
- lineas.push(`| \`${c.comando}\` | ${c.proposito} |`);
96
- }
97
- lineas.push('');
98
- }
99
-
100
- // ─── Sistema SWL (siempre presente) ────────────────────────────────────
101
- lineas.push('## Sistema SWL — uso obligatorio');
102
- lineas.push('');
103
- lineas.push(`Este proyecto usa swl-ses v${contexto.version} (sistema de ingeniería de software auto-evolutivo multi-runtime).`);
104
- lineas.push(`Componentes instalados: ${contexto.conteos?.agentes || 0} agentes, ${contexto.conteos?.skills || 0} skills, ${contexto.conteos?.comandos || 0} comandos, ${contexto.conteos?.reglas || 0} reglas.`);
105
- lineas.push('');
106
-
107
- lineas.push('### Reglas de máxima prioridad');
108
- lineas.push('');
109
- lineas.push('1. **Idioma: español de México** — respuestas, código comentado, commits, PRs y docs. Evitar anglicismos innecesarios.');
110
- lineas.push('2. **Usar el sistema SWL** — invocar agentes especializados (`orquestador-swl`, `implementador-swl`, `depurador-swl`, etc.) en lugar de hacer trabajo directo. Cargar skills con `Skill("nombre")` antes de implementar. Usar comandos `/swl:*` cuando apliquen.');
111
- lineas.push('3. **Investigar antes de editar** — leer el archivo completo y entender el contexto antes de modificar código.');
112
- lineas.push('4. **Lectura de documentos Office/Jupyter** — usar `python scripts/vendor/markitdown/cli.py <archivo>` para `.docx`, `.xlsx`, `.pptx`, `.ipynb`. El Read tool no soporta esos formatos.');
113
- lineas.push('');
114
-
115
- lineas.push('### Dónde están los componentes');
116
- lineas.push('');
117
- lineas.push('- Agentes: `.claude/agents/*.md`');
118
- lineas.push('- Skills: `.claude/skills/*/SKILL.md` (invocar con `Skill("nombre")`)');
119
- lineas.push('- Comandos: `.claude/commands/swl/*.md` (invocar con `/swl:nombre`)');
120
- lineas.push('- Reglas: `.claude/rules/*.md` (se cargan automáticamente)');
121
- lineas.push('- Hooks: registrados en `.claude/settings.json`');
122
- lineas.push('');
123
-
124
- lineas.push('### Flujos recomendados');
125
- lineas.push('');
126
- lineas.push('- **Feature completa**: `/swl:discutir-fase N` → `/swl:planear-fase N` → `/swl:ejecutar-fase N` → `/swl:verificar`');
127
- lineas.push('- **Debugging**: delegar a `depurador-swl` con método científico (reproducir → aislar → hipótesis → fix → verificar)');
128
- lineas.push('- **Calidad**: `/swl:revisar` (código) + `revisor-seguridad-swl` antes de merge a main');
129
- lineas.push('- **Aprendizaje continuo**: `/swl:aprender` al final de fase, `/swl:evolucionar` ante fallos recurrentes de agentes');
130
- lineas.push('');
131
-
132
- lineas.push('### Consulta del sistema');
133
- lineas.push('');
134
- lineas.push('- `/swl:ayuda` — catálogo completo de comandos');
135
- lineas.push('- `/swl:salud` — diagnóstico de integridad (incluye calidad de CLAUDE.md)');
136
- lineas.push('- `/swl:metricas` — tokens, costo y modelos usados en la sesión');
137
- lineas.push('- `/swl:skill-search <keyword>` — buscar skills relevantes');
138
- lineas.push('- `/swl:claudemd audit` — auditar este CLAUDE.md (líneas, bullets gigantes, secciones canónicas)');
139
- lineas.push('');
140
-
141
- lineas.push('### Convenciones de versionado y commits');
142
- lineas.push('');
143
- lineas.push('- Versionado semántico estricto (SemVer)');
144
- lineas.push('- Mensajes de commit en español, formato `<tipo>(<scope>): <descripción en imperativo>`');
145
- lineas.push('- Commits atómicos (un cambio lógico = un commit)');
146
- lineas.push('- Antes de release: `/swl:release` y gate `node scripts/verificar-release.js`');
147
- lineas.push('');
148
-
149
- // ─── Jerarquía project / user-level (best practice Anthropic) ─────────
150
- lineas.push('### Jerarquía de CLAUDE.md (recomendada)');
151
- lineas.push('');
152
- lineas.push('- **Project-level** (este archivo, `./CLAUDE.md`) — convenciones del proyecto, compartido vía VCS con el equipo.');
153
- lineas.push('- **User-level** (`~/.claude/CLAUDE.md`) — preferencias personales transversales (estilo de comentarios, lenguaje preferido, atajos personales). NO se commitea.');
154
- lineas.push('- Las **reglas globales** del usuario en `~/.claude/rules/*.md` se cargan automáticamente para todos los proyectos.');
155
- lineas.push('- Si no tienes user-level, créalo con `/swl:claudemd init-user`.');
156
- lineas.push('');
157
-
158
- // ─── Patrón "ask Claude to save to memory" del video oficial ──────────
159
- lineas.push('### Cómo evolucionar este archivo');
160
- lineas.push('');
161
- lineas.push('1. **Empieza mínimo**. No adelantes reglas. Agrega solo lo que tengas que corregir más de una vez.');
162
- lineas.push('2. **Cuando corrijas a Claude**, pide explícitamente: *"guarda esto en memoria"* o *"agrega esto a CLAUDE.md"*. Esa es la forma natural de que el archivo crezca con valor.');
163
- lineas.push('3. **Usa `@filepath`** para referenciar docs sin duplicar contenido (ej. `@docs/api.md`, `@.planning/PROYECTO.md`).');
164
- lineas.push('4. **Si crece mucho**, ejecuta `/swl:claudemd refactor` para extraer secciones a archivos `@`-referenciados.');
165
- lineas.push('');
166
-
167
- return {
168
- contenido: lineas.join('\n'),
169
- rutaRelativa: 'CLAUDE.md',
170
- dirBase: '.',
171
- merge: {
172
- tipo: 'marcadores',
173
- beginTag: `<!-- SWL-BEGIN v${contexto.version} — bloque gestionado por swl-ses -->`,
174
- endTag: '<!-- SWL-END -->',
175
- beginPrefix: '<!-- SWL-BEGIN',
176
- },
177
- };
178
- }
179
-
180
- transformarHooks(hooksConfig, opciones) {
181
- // Los hooks de Claude se manejan via hooks-settings.js existente
182
- return { formato: 'claude-settings', config: hooksConfig };
183
- }
184
-
185
- /**
186
- * Wrapper defensivo: si la detección de stack falla por cualquier razón
187
- * (permisos, archivo corrupto, etc.), se ignora y se genera el bloque
188
- * sin secciones de stack. NUNCA romper el installer.
189
- */
190
- _detectarStackSeguro(dirProyecto) {
191
- try {
192
- return detectarStackDetallado(dirProyecto);
193
- } catch (e) {
194
- // Silencioso: stack no detectado, bloque base se genera igualmente
195
- return null;
196
- }
197
- }
198
- }
199
-
200
- module.exports = TransformadorClaude;
1
+ 'use strict';
2
+
3
+ const TransformadorBase = require('./base');
4
+ const { detectarStackDetallado } = require('../detectar-stack-detallado');
5
+
6
+ class TransformadorClaude extends TransformadorBase {
7
+ transformarAgente(contenidoMd, metadatos) {
8
+ // Pass-through: Claude soporta el formato SWL directamente
9
+ return {
10
+ contenido: contenidoMd,
11
+ rutaRelativa: `agents/${metadatos.nombreArchivo}`,
12
+ };
13
+ }
14
+
15
+ transformarSkill(dirSkill, metadatos) {
16
+ // Pass-through: copiar directorio completo
17
+ return {
18
+ tipo: 'directorio',
19
+ rutaRelativa: `skills/${metadatos.nombreDirectorio}`,
20
+ };
21
+ }
22
+
23
+ transformarRegla(contenidoMd, metadatos) {
24
+ return {
25
+ contenido: contenidoMd,
26
+ rutaRelativa: `rules/${metadatos.nombreArchivo}`,
27
+ };
28
+ }
29
+
30
+ transformarComando(contenidoMd, metadatos) {
31
+ return {
32
+ contenido: contenidoMd,
33
+ rutaRelativa: `commands/swl/${metadatos.nombreArchivo}`,
34
+ };
35
+ }
36
+
37
+ /**
38
+ * Genera el bloque SWL para insertar en el CLAUDE.md del proyecto destino.
39
+ *
40
+ * A diferencia de los otros transformadores (codex/gemini/copilot/opencode)
41
+ * que generan el archivo completo de instrucciones desde cero, Claude usa
42
+ * un CLAUDE.md que el usuario mantiene y que puede tener contenido propio
43
+ * (reglas del proyecto, convenciones, notas). Por eso:
44
+ *
45
+ * - El contenido devuelto es un BLOQUE (no archivo completo)
46
+ * - Se devuelve `merge: { tipo: 'marcadores', ... }` para indicar al
47
+ * caller que debe usar `append-con-marcadores` en lugar de writeFileSync
48
+ * - Los marcadores `<!-- SWL-BEGIN vX.Y.Z -->` / `<!-- SWL-END -->`
49
+ * permiten que la siguiente actualización reemplace solo este bloque
50
+ * sin tocar el contenido del usuario
51
+ *
52
+ * Aplicación de ADR-0016 (best practices Anthropic "The CLAUDE.md file"):
53
+ * - Detecta stack del proyecto destino (lenguaje, framework, ORM,
54
+ * package manager, comandos disponibles)
55
+ * - Genera secciones canónicas: Stack / Comandos del proyecto / Sistema SWL
56
+ * - Documenta jerarquía project / user-level (`~/.claude/CLAUDE.md`)
57
+ * - Documenta patrón "ask Claude to save to memory" del video oficial
58
+ */
59
+ generarArchivoInstrucciones(contexto) {
60
+ const fecha = new Date().toISOString().split('T')[0];
61
+ const stack = contexto.dirProyecto
62
+ ? this._detectarStackSeguro(contexto.dirProyecto)
63
+ : null;
64
+
65
+ const lineas = [
66
+ `> Gestionado por swl-ses v${contexto.version} — no editar entre estos marcadores.`,
67
+ `> Regenerado en ${fecha} con perfil \`${contexto.perfil || 'default'}\`.`,
68
+ `> Para excluir este bloque en futuras actualizaciones: \`npx @saulwade/swl-ses@latest install --no-claudemd\`.`,
69
+ '',
70
+ ];
71
+
72
+ // ─── Stack del proyecto detectado (best practice Anthropic #2) ─────────
73
+ if (stack && stack.detectado) {
74
+ lineas.push('## Stack del proyecto');
75
+ lineas.push('');
76
+ const partes = [];
77
+ if (stack.lenguajePrincipal) {
78
+ partes.push(`**Lenguaje**: ${stack.lenguajePrincipal.lenguaje}` +
79
+ (stack.lenguajePrincipal.runtime ? ` (${stack.lenguajePrincipal.runtime})` : ''));
80
+ }
81
+ if (stack.framework) partes.push(`**Framework**: ${stack.framework}`);
82
+ if (stack.orm) partes.push(`**ORM/BD**: ${stack.orm}`);
83
+ if (stack.packageManager) partes.push(`**Package manager**: ${stack.packageManager}`);
84
+ lineas.push('- ' + partes.join('\n- '));
85
+ lineas.push('');
86
+ }
87
+
88
+ // ─── Comandos del proyecto (best practice Anthropic #3) ────────────────
89
+ if (stack && stack.comandos && stack.comandos.length > 0) {
90
+ lineas.push('## Comandos del proyecto');
91
+ lineas.push('');
92
+ lineas.push('| Comando | Propósito |');
93
+ lineas.push('|---------|-----------|');
94
+ for (const c of stack.comandos) {
95
+ lineas.push(`| \`${c.comando}\` | ${c.proposito} |`);
96
+ }
97
+ lineas.push('');
98
+ }
99
+
100
+ // ─── Sistema SWL (siempre presente) ────────────────────────────────────
101
+ lineas.push('## Sistema SWL — uso obligatorio');
102
+ lineas.push('');
103
+ lineas.push(`Este proyecto usa swl-ses v${contexto.version} (sistema de ingeniería de software auto-evolutivo multi-runtime).`);
104
+ lineas.push(`Componentes instalados: ${contexto.conteos?.agentes || 0} agentes, ${contexto.conteos?.skills || 0} skills, ${contexto.conteos?.comandos || 0} comandos, ${contexto.conteos?.reglas || 0} reglas.`);
105
+ lineas.push('');
106
+
107
+ lineas.push('### Reglas de máxima prioridad');
108
+ lineas.push('');
109
+ lineas.push('1. **Idioma: español de México** — respuestas, código comentado, commits, PRs y docs. Evitar anglicismos innecesarios.');
110
+ lineas.push('2. **Usar el sistema SWL** — invocar agentes especializados (`orquestador-swl`, `implementador-swl`, `depurador-swl`, etc.) en lugar de hacer trabajo directo. Cargar skills con `Skill("nombre")` antes de implementar. Usar comandos `/swl:*` cuando apliquen.');
111
+ lineas.push('3. **Investigar antes de editar** — leer el archivo completo y entender el contexto antes de modificar código.');
112
+ lineas.push('4. **Lectura de documentos Office/Jupyter** — usar `python scripts/vendor/markitdown/cli.py <archivo>` para `.docx`, `.xlsx`, `.pptx`, `.ipynb`. El Read tool no soporta esos formatos.');
113
+ lineas.push('');
114
+
115
+ lineas.push('### Dónde están los componentes');
116
+ lineas.push('');
117
+ lineas.push('- Agentes: `.claude/agents/*.md`');
118
+ lineas.push('- Skills: `.claude/skills/*/SKILL.md` (invocar con `Skill("nombre")`)');
119
+ lineas.push('- Comandos: `.claude/commands/swl/*.md` (invocar con `/swl:nombre`)');
120
+ lineas.push('- Reglas: `.claude/rules/*.md` (se cargan automáticamente)');
121
+ lineas.push('- Hooks: registrados en `.claude/settings.json`');
122
+ lineas.push('');
123
+
124
+ lineas.push('### Flujos recomendados');
125
+ lineas.push('');
126
+ lineas.push('- **Feature completa**: `/swl:discutir-fase N` → `/swl:planear-fase N` → `/swl:ejecutar-fase N` → `/swl:verificar`');
127
+ lineas.push('- **Debugging**: delegar a `depurador-swl` con método científico (reproducir → aislar → hipótesis → fix → verificar)');
128
+ lineas.push('- **Calidad**: `/swl:revisar` (código) + `revisor-seguridad-swl` antes de merge a main');
129
+ lineas.push('- **Aprendizaje continuo**: `/swl:aprender` al final de fase, `/swl:evolucionar` ante fallos recurrentes de agentes');
130
+ lineas.push('');
131
+
132
+ lineas.push('### Consulta del sistema');
133
+ lineas.push('');
134
+ lineas.push('- `/swl:ayuda` — catálogo completo de comandos');
135
+ lineas.push('- `/swl:salud` — diagnóstico de integridad (incluye calidad de CLAUDE.md)');
136
+ lineas.push('- `/swl:metricas` — tokens, costo y modelos usados en la sesión');
137
+ lineas.push('- `/swl:skill-search <keyword>` — buscar skills relevantes');
138
+ lineas.push('- `/swl:claudemd audit` — auditar este CLAUDE.md (líneas, bullets gigantes, secciones canónicas)');
139
+ lineas.push('');
140
+
141
+ lineas.push('### Convenciones de versionado y commits');
142
+ lineas.push('');
143
+ lineas.push('- Versionado semántico estricto (SemVer)');
144
+ lineas.push('- Mensajes de commit en español, formato `<tipo>(<scope>): <descripción en imperativo>`');
145
+ lineas.push('- Commits atómicos (un cambio lógico = un commit)');
146
+ lineas.push('- Antes de release: `/swl:release` y gate `node scripts/verificar-release.js`');
147
+ lineas.push('');
148
+
149
+ // ─── Jerarquía project / user-level (best practice Anthropic) ─────────
150
+ lineas.push('### Jerarquía de CLAUDE.md (recomendada)');
151
+ lineas.push('');
152
+ lineas.push('- **Project-level** (este archivo, `./CLAUDE.md`) — convenciones del proyecto, compartido vía VCS con el equipo.');
153
+ lineas.push('- **User-level** (`~/.claude/CLAUDE.md`) — preferencias personales transversales (estilo de comentarios, lenguaje preferido, atajos personales). NO se commitea.');
154
+ lineas.push('- Las **reglas globales** del usuario en `~/.claude/rules/*.md` se cargan automáticamente para todos los proyectos.');
155
+ lineas.push('- Si no tienes user-level, créalo con `/swl:claudemd init-user`.');
156
+ lineas.push('');
157
+
158
+ // ─── Patrón "ask Claude to save to memory" del video oficial ──────────
159
+ lineas.push('### Cómo evolucionar este archivo');
160
+ lineas.push('');
161
+ lineas.push('1. **Empieza mínimo**. No adelantes reglas. Agrega solo lo que tengas que corregir más de una vez.');
162
+ lineas.push('2. **Cuando corrijas a Claude**, pide explícitamente: *"guarda esto en memoria"* o *"agrega esto a CLAUDE.md"*. Esa es la forma natural de que el archivo crezca con valor.');
163
+ lineas.push('3. **Usa `@filepath`** para referenciar docs sin duplicar contenido (ej. `@docs/api.md`, `@.planning/PROYECTO.md`).');
164
+ lineas.push('4. **Si crece mucho**, ejecuta `/swl:claudemd refactor` para extraer secciones a archivos `@`-referenciados.');
165
+ lineas.push('');
166
+
167
+ return {
168
+ contenido: lineas.join('\n'),
169
+ rutaRelativa: 'CLAUDE.md',
170
+ dirBase: '.',
171
+ merge: {
172
+ tipo: 'marcadores',
173
+ beginTag: `<!-- SWL-BEGIN v${contexto.version} — bloque gestionado por swl-ses -->`,
174
+ endTag: '<!-- SWL-END -->',
175
+ beginPrefix: '<!-- SWL-BEGIN',
176
+ },
177
+ };
178
+ }
179
+
180
+ transformarHooks(hooksConfig, opciones) {
181
+ // Los hooks de Claude se manejan via hooks-settings.js existente
182
+ return { formato: 'claude-settings', config: hooksConfig };
183
+ }
184
+
185
+ /**
186
+ * Wrapper defensivo: si la detección de stack falla por cualquier razón
187
+ * (permisos, archivo corrupto, etc.), se ignora y se genera el bloque
188
+ * sin secciones de stack. NUNCA romper el installer.
189
+ */
190
+ _detectarStackSeguro(dirProyecto) {
191
+ try {
192
+ return detectarStackDetallado(dirProyecto);
193
+ } catch (e) {
194
+ // Silencioso: stack no detectado, bloque base se genera igualmente
195
+ return null;
196
+ }
197
+ }
198
+ }
199
+
200
+ module.exports = TransformadorClaude;
@@ -39,7 +39,7 @@ class TransformadorCodex extends TransformadorBase {
39
39
  lineas.push('# AGENTS.md — Sistema SWL');
40
40
  lineas.push('');
41
41
  lineas.push(`> Generado por swl-ses v${contexto.version} — ${new Date().toISOString().split('T')[0]}`);
42
- lineas.push('> NO editar manualmente. Regenerar con: npx swl-ses@latest install --target codex');
42
+ lineas.push('> NO editar manualmente. Regenerar con: npx @saulwade/swl-ses@latest install --target codex');
43
43
  lineas.push('');
44
44
  lineas.push(`Sistema: swl-ses v${contexto.version}`);
45
45
  lineas.push(`Perfil: ${contexto.perfil}`);
@@ -47,7 +47,7 @@ class TransformadorCopilot extends TransformadorBase {
47
47
  lineas.push('# Instrucciones del proyecto — SWL');
48
48
  lineas.push('');
49
49
  lineas.push(`> Generado por swl-ses v${contexto.version} — ${new Date().toISOString().split('T')[0]}`);
50
- lineas.push('> NO editar manualmente. Regenerar con: npx swl-ses@latest install --target copilot');
50
+ lineas.push('> NO editar manualmente. Regenerar con: npx @saulwade/swl-ses@latest install --target copilot');
51
51
  lineas.push('');
52
52
 
53
53
  if (contexto.reglas && contexto.reglas.length > 0) {
@@ -46,7 +46,7 @@ class TransformadorGemini extends TransformadorBase {
46
46
  lineas.push('# GEMINI.md — Sistema SWL');
47
47
  lineas.push('');
48
48
  lineas.push(`> Generado por swl-ses v${contexto.version} — ${new Date().toISOString().split('T')[0]}`);
49
- lineas.push('> NO editar manualmente. Regenerar con: npx swl-ses@latest install --target gemini');
49
+ lineas.push('> NO editar manualmente. Regenerar con: npx @saulwade/swl-ses@latest install --target gemini');
50
50
  lineas.push('');
51
51
  lineas.push(`Este proyecto usa el sistema SWL con perfil "${contexto.perfil}".`);
52
52
  lineas.push('');
@@ -47,7 +47,7 @@ class TransformadorOpenCode extends TransformadorBase {
47
47
  lineas.push('# AGENTS.md — Sistema SWL');
48
48
  lineas.push('');
49
49
  lineas.push(`> Generado por swl-ses v${contexto.version} — ${new Date().toISOString().split('T')[0]}`);
50
- lineas.push('> NO editar manualmente. Regenerar con: npx swl-ses@latest install --target opencode');
50
+ lineas.push('> NO editar manualmente. Regenerar con: npx @saulwade/swl-ses@latest install --target opencode');
51
51
  lineas.push('');
52
52
  lineas.push(`Este proyecto usa el sistema SWL con perfil "${contexto.perfil}".`);
53
53
  lineas.push('');