@tacuchi/agent-workflow-cli 6.1.0 → 7.0.0

package/skills/agent-workflow/exports/export-scripts/references/theme-handling.md

@@ -0,0 +1,168 @@
+# Theme handling — detección + consolidación + ORDER cross-tema
+
+> **Port adaptado** de `release-scripts/references/theme-detection.md` + `release-scripts/references/order-generation.md` (ambos v2.0.0). DEC-004 de session061: contenido equivalente, paths actualizados al output dir único de export-scripts.
+
+## Activación de la vista `por-tema/`
+
+`por-tema/` se genera **sólo** si se cumple **alguna** de estas condiciones:
+
+1. `--themes slug1,slug2` declarado explícitamente.
+2. Al menos una de las sesiones incluidas tiene sección `## Temas` en su `OBJECTIVE.md` (o `OBJETIVO.md` legacy).
+3. `--themes infer` declarado (inferencia LLM con confirmación).
+
+Si **ninguna** se cumple: el output dir contiene solo `por-sesion/` + archivos top-level. No se crea sub-carpeta `por-tema/` vacía.
+
+## Formato de `## Temas` en OBJECTIVE
+
+```markdown
+## Temas
+
+- `rbac`: gestión de roles y permisos
+- `lista-negra-blanca`: filtros de acceso
+- `auditoria`: logging de cambios sensibles
+```
+
+Reglas:
+- Slug kebab-case (`a-z0-9-`).
+- Una descripción breve por tema (ayuda a la inferencia cross-session).
+- Sin overlapping en una misma sesión salvo necesidad expresa.
+
+## Resolución de temas por sesión
+
+### Paso A — Lectura declarativa
+
+Para cada sesión incluida, leer `OBJECTIVE.md` (fallback bilingual a `OBJETIVO.md`) buscando sección `## Temas`. Si presente: extraer slugs como autoritativos para esa sesión.
+
+### Paso B — Inferencia LLM (si `--themes infer` o falta declarativo en N sesiones)
+
+Para cada sesión sin `## Temas`:
+
+1. Leer OBJECTIVE + nombres de scripts SQL.
+2. Inferir temas candidatos (3-5 max) con confidence score 0-1.
+3. Proponer al usuario:
+   ```
+   Sesión session057:
+   - Tema candidato: `export-report` (confidence 0.92, scripts: ...)
+   - Tema candidato: `lifecycle-extension` (confidence 0.45)
+   - ¿Aceptar / editar / declarar uno propio?
+   ```
+4. Persistir respuesta:
+   - Si sesión **activa**: escribir `## Temas` en OBJECTIVE.
+   - Si sesión **cerrada**: guardar en `por-tema/themes.inferred.md` del bundle (no toca artefactos cerrados).
+
+### Paso C — Filtro `--themes`
+
+Si `--themes slug1,slug2` declarado: restringir el output `por-tema/` a esos slugs. Scripts cuyo tema no entre en el filtro caen en `por-sesion/` solamente (no aparecen en `por-tema/`).
+
+## Asignación de cada script a su tema
+
+Por cada `.sql` forward de las sesiones incluidas:
+
+1. **Header declarativo**: leer primeras 10 líneas buscando `-- Temas: slug1, slug2`. Si presente: usa esos slugs.
+2. **Por nombre**: matchear contra patrones del tema (substring del slug en el filename, ej. `rbac-rol-permiso.sql` → `rbac`).
+3. **Por contenido**: leer el SQL y aplicar heurística (qué tabla/función toca, qué módulo de negocio).
+4. **Fallback**: si nada matchea, asignar a `tema-general/` con warning en el manifest.
+
+### Multi-tema
+
+Si un script aplica a 2+ temas: copia al primer tema declarado y crea `.link.md` en los demás referenciando el canónico:
+
+```markdown
+# Link — script multi-tema
+
+Este script aplica al tema `[secundario]` pero su versión canónica vive en:
+
+- `por-tema/tema-[primario]/03-migracion.sql` (sección [N], script `[nombre-original.sql]`)
+
+Razón: el header declarativo del script lista temas múltiples, y por convención el primero es el canónico.
+```
+
+## Consolidación por categoría dentro de cada tema
+
+Para cada tema y cada categoría (01..04):
+
+1. Ordenar scripts fuente por NNN original (cronológico cross-session).
+2. Leer cada `.sql`, extraer cuerpo eliminando `BEGIN;` inicial y `COMMIT;` final.
+3. Concatenar con separadores `[i/N]` + nombre + ruta canónica.
+4. Envolver todo en un único `BEGIN; … COMMIT;`.
+5. Escribir `por-tema/tema-<slug>/<categoria>.sql`.
+6. Consolidar `.rollback.sql` en orden inverso.
+
+### Header del consolidado
+
+**Uno solo** al inicio del archivo, con el formato canónico de 4 líneas definido en `sql-script-organizer/SKILL.md#header-canónico`:
+
+```
+-- Script: tema-rbac/03-migracion.sql
+-- Sesion: s057, s058, s063
+-- Objeto: migración de roles y asignaciones RBAC
+-- Alcance: tablas tb_rol, tb_permiso_rol, tb_rol_usuario
+```
+
+**No copiar** los headers de los scripts individuales — su origen queda registrado en los separadores `[i/N]` del cuerpo y en `README.md`.
+
+### `--keep-parts`
+
+Si el flag está activo: preservar `por-tema/<slug>/parts/<categoria>/*.sql` con los scripts individuales (no consolidados). Permite ejecutar uno por vez para debugging.
+
+## Rollback por tema y global
+
+### `por-tema/tema-<slug>/rollback-tema-<slug>.sql`
+
+Encadena los 4 consolidados de rollback (04→03→02→01) dentro de un único `BEGIN; … COMMIT;`. Operaciones irreversibles marcadas con header WARNING.
+
+### `rollback-global.sql` (en output dir top-level)
+
+Encadena rollback por-tema en orden **inverso a `ORDER.md`**. Si `por-tema/` no existe, encadena `por-sesion/<sessionXXX>/rollback/*.sql` por sesión cronológica inversa.
+
+Algoritmo completo en `sql-rollback-generator/references/release-rollback.md` (referenciable cross-skill).
+
+## `ORDER.md` cross-tema
+
+Cuando hay `por-tema/`: el `ORDER.md` top-level del bundle intercala scripts por **fase** (no por tema):
+
+```markdown
+## Fase 1 — DDL tablas
+
+psql -f por-tema/tema-rbac/01-ddl-tablas.sql
+psql -f por-tema/tema-lista-negra-blanca/01-ddl-tablas.sql
+psql -f por-tema/tema-auditoria/01-ddl-tablas.sql
+
+## Fase 2 — DDL funciones
+
+psql -f por-tema/tema-rbac/02-ddl-funciones.sql
+...
+
+## Fase 3 — Migración
+
+...
+
+## Fase 4 — Inserts iniciales
+
+...
+
+## Fase 5 — Cleanup irreversible
+
+(operaciones DROP COLUMN, TRUNCATE, DROP CASCADE — al final)
+```
+
+Cuando **no** hay `por-tema/`: el `ORDER.md` lista scripts por sesión cronológica, dentro de cada una 01→04:
+
+```markdown
+## Sesión session057-export-func
+
+psql -f por-sesion/session057-export-func/01-ddl-tablas/001-...sql
+psql -f por-sesion/session057-export-func/02-ddl-funciones/001-...sql
+...
+
+## Sesión session058-export-arq
+
+...
+```
+
+## Idempotencia
+
+- Re-ejecutar export-scripts con los mismos args sobre las mismas sesiones produce el **mismo** output **modulo el NNN nuevo** del directorio. Cada invocación toma siguiente NNN; no sobrescribe.
+- Para regenerar: borrar el directorio manualmente y re-invocar.
+- Si los temas se declararon en OBJECTIVE: sin re-confirmación.
+- Si fueron inferidos: re-propone con `--themes infer`.

package/skills/agent-workflow/exports/export-scripts/references/validations.md

@@ -0,0 +1,242 @@
+# Validations — V1-V6 para `/agent-workflow:export-scripts`
+
+Checks post-render que se aplican antes de escribir el bundle al filesystem. Adaptados del canon de la familia export-* (export-arq + export-report) con foco en bundle SQL + informe.
+
+Niveles de severidad:
+- **Hard-fail**: aborta la escritura, devuelve `ok: false` con error report. No se crea el directorio.
+- **Warning**: emite mensaje, pide confirmación del usuario para continuar.
+
+## V1 — Estructura del bundle
+
+**Severidad**: hard-fail si falta archivo obligatorio o sub-dir esperado.
+
+**Archivos obligatorios siempre**:
+- `manifest.md`
+- `README.md`
+- `ORDER.md`
+- `rollback-global.sql`
+- `por-sesion/` con ≥1 sesión
+
+**Archivos condicionales**:
+- `por-tema/` con ≥1 tema — sólo si la activación de Paso 6 dio positivo (themes declarados, `## Temas` en OBJECTIVE, o `--themes infer`).
+
+**Cómo validar**: listar el output dir antes de escribir el manifest final; verificar que todos los archivos obligatorios estarán presentes.
+
+**Error report (hard-fail)**:
+```
+V1 FAILED: bundle incompleto
+  esperado: manifest.md, README.md, ORDER.md, rollback-global.sql, por-sesion/
+  encontrado: manifest.md, README.md, por-sesion/
+  faltantes: ORDER.md, rollback-global.sql
+  acción: regenerar pasos 7 y 9
+```
+
+## V2 — Noise vetado
+
+**Severidad**: hard-fail si hay ≥1 ocurrencia en el cuerpo del `manifest.md` (header y sección Metadata exentos).
+
+**Scope**: body-only — líneas después de `# Informe del bundle NNN` (h1 inicial) y antes de `## 10. Metadata`.
+
+**Cómo validar**:
+```bash
+awk '
+  BEGIN { body=0 }
+  /^## 10\. Metadata/ { body=0 }
+  body { print }
+  /^# / && !/Metadata/ { body=1 }
+' manifest.md > /tmp/body.md
+grep -n -F -f references/lexico-tecnico.md /tmp/body.md
+```
+
+**Error report (hard-fail)**:
+```
+V2 FAILED: noise vetado detectado en cuerpo del manifest
+  ocurrencias:
+    línea 12: "NNN-export-scripts-YYYY-MM-DD"  → placeholder sin reemplazar
+    línea 28: "/Users/tacuchi/"                → path absoluto del developer
+    línea 41: "DEC-NNN"                        → placeholder sin reemplazar
+  total: 3 ocurrencias
+  acción: completar render y stripear paths absolutos
+```
+
+## V3 — Secciones obligatorias del manifest
+
+**Severidad**: hard-fail si falta una sección obligatoria.
+
+**Secciones obligatorias** (todas siempre presentes en `manifest.md`):
+1. `## 1. Resumen ejecutivo`
+2. `## 2. Sesiones incluidas`
+3. `## 3. Acciones manuales previas a producción`
+4. `## 4. Base de datos`
+5. `## 5. Código fuente — hallazgos del escaneo`
+6. `## 6. Git y ramas`
+7. `## 7. Documentación graduada`
+8. `## 8. Checklist final de producción`
+9. `## 9. Advertencias`
+10. `## 10. Metadata`
+
+**Cómo validar**:
+```bash
+grep -c '^## [0-9]\+\. ' manifest.md  # debe dar exactamente 10
+```
+
+**Error report (hard-fail)**:
+```
+V3 FAILED: secciones obligatorias faltantes
+  esperadas: 10
+  encontradas: 8
+  faltantes: "## 5. Código fuente — hallazgos del escaneo", "## 9. Advertencias"
+  acción: regenerar manifest con secciones completas
+```
+
+## V4 — Secciones condicionales honored
+
+**Severidad**: hard-fail si una sub-sección condicional aparece sin justificación o falta cuando debería estar.
+
+### V4.a — Vista por tema (`## 4.4 Vista por tema`)
+
+- **Patrón A — activada**: temas declarados (CLI flag o `## Temas`) → sub-sección `## 4.4 Vista por tema` presente con conteo + paths a `por-tema/`.
+- **Patrón B — no activada**: sin temas → sub-sección `## 4.4 Vista por tema` **ausente** (no aparece header ni placeholder).
+
+**Error report (Patrón B esperado pero sección presente sin contenido)**:
+```
+V4.a FAILED: sin temas declarados pero sección "## 4.4 Vista por tema" presente
+  themes: []
+  acción: omitir sección cuando no hay temas (no dejar placeholder)
+```
+
+### V4.b — Code scan skip (`## 5`)
+
+- **Patrón A — escaneo ejecutado**: sección 5 contiene resumen con counts (`X críticos · Y medios · Z bajos`).
+- **Patrón B — `--skip-code-scan`**: sección 5 contiene **nota inline explícita** `_(Escaneo omitido por --skip-code-scan)_` y no hay tabla de hallazgos.
+
+**Error report (Patrón B esperado pero tabla presente)**:
+```
+V4.b FAILED: --skip-code-scan declarado pero sección 5 tiene tabla de hallazgos
+  args: --skip-code-scan
+  acción: reemplazar tabla por nota inline
+```
+
+### V4.c — Sesiones abiertas
+
+- **Patrón A — sesiones cerradas**: tabla "## 2. Sesiones incluidas" sin warnings ⚠.
+- **Patrón B — sesiones activas incluidas**: cada sesión activa marcada con ⚠ + motivo de apertura en la columna "Resumen".
+
+**Error report (Patrón B sin ⚠)**:
+```
+V4.c FAILED: sesiones activas detectadas pero no marcadas con ⚠
+  sesiones activas: session061
+  acción: marcar con ⚠ en tabla y documentar motivo en columna Resumen
+```
+
+## V5 — Header bien formado
+
+**Severidad**: warning.
+
+**Checks** (líneas 1-5 del `manifest.md`):
+- Línea 1: `# Informe del bundle NNN — <YYYY-MM-DD>` con NNN reemplazado.
+- Línea 3: `- **Rama actual:** \`<nombre-rama>\``
+- Línea 4: `- **Rama destino:** \`certificacion\``
+- Línea 5: `- **Sesiones incluidas:** <N>`
+- Línea 6: `- **Readiness:** 🟢 verde | 🟡 amarillo | 🔴 rojo` (una sola opción seleccionada).
+- Línea 7: `- **Generado por:** agent-workflow · skill \`export-scripts\``
+
+**Error report (warning)**:
+```
+V5 WARNING: header incompleto o malformado
+  línea 1: OK
+  línea 3: "- **Rama actual:** `<nombre-rama>`" → placeholder sin reemplazar
+  acción: re-renderizar header con valores reales
+  ¿continuar de todas formas? (s/n)
+```
+
+## V6 — Referencias resolubles
+
+**Severidad**: warning.
+
+**Checks**: cada link en cualquier sección del manifest apunta a un path existente en filesystem al momento de generar.
+
+**Cómo validar**:
+```bash
+grep -Eo '`[^`]+\.(md|sql)`|\[.+?\]\([^)]+\)' manifest.md | \
+  sed -E 's/^`(.+)`$/\1/; s/^\[.+?\]\((.+)\)$/\1/' | \
+  while read p; do
+    if [ ! -e "$p" ] && [ ! -e "<output_dir>/$p" ]; then echo "MISSING: $p"; fi
+  done
+```
+
+**Excepción**: links a `docs/decisiones/`, `docs/manuales/`, etc. **fuera** del output dir son válidos si existen en el workspace; si no, warning suave (no aborta).
+
+**Error report (warning)**:
+```
+V6 WARNING: 2 referencias apuntan a paths inexistentes
+  - docs/decisiones/005-tipos-cobranza.md → no existe en workspace
+  - por-sesion/session999/01-ddl-tablas/  → no existe en output dir
+  acción sugerida: corregir paths o omitir referencias placeholder
+  ¿continuar de todas formas? (s/n)
+```
+
+## Orden de aplicación
+
+1. V1 (estructura del bundle) — primero, barato.
+2. V3 (secciones del manifest) — segundo, barato.
+3. V2 (noise vetado) — tercero, requiere lectura del body.
+4. V4 (condicionales) — cuarto, requiere reconstruir contexto de flags + corpus.
+5. V5 (header) — quinto.
+6. V6 (referencias resolubles) — último.
+
+Si V1, V3 o V4 fallan → abortar inmediatamente.
+Si V2 falla → abortar (no warning, igual que en export-arq y export-report).
+Si V5 o V6 emiten warning → pedir confirmación al usuario.
+
+## Reporte consolidado
+
+Al final del flujo, el skill devuelve:
+
+```json
+{
+  "ok": true,
+  "output_dir": "docs/scripts/NNN-export-scripts-YYYY-MM-DD/",
+  "files_written": [
+    "manifest.md", "README.md", "ORDER.md", "rollback-global.sql",
+    "por-sesion/session057-export-func/...",
+    "por-sesion/session058-export-arq/...",
+    "por-tema/tema-rbac/01-ddl-tablas.sql",
+    "..."
+  ],
+  "themes_resolved": ["rbac", "lista-negra-blanca"],
+  "sessions_included": ["057", "058", "059", "060"],
+  "validations": {
+    "V1": { "status": "pass" },
+    "V2": { "status": "pass", "noise_hits": 0 },
+    "V3": { "status": "pass", "sections_found": 10 },
+    "V4": { "status": "pass", "conditionals": { "por_tema": "presente (2 temas)", "code_scan": "ejecutado", "sesiones_abiertas": "0" } },
+    "V5": { "status": "pass" },
+    "V6": { "status": "warning", "missing_refs": ["docs/decisiones/005-...md"] }
+  },
+  "summary": "Bundle escrito. 1 warning (V6) aceptado."
+}
+```
+
+Si hard-fail:
+
+```json
+{
+  "ok": false,
+  "stage": "validation",
+  "failed_at": "V3",
+  "details": "secciones obligatorias faltantes: ## 5. Código fuente — hallazgos del escaneo",
+  "no_files_written": true
+}
+```
+
+## Diferencias con `export-arq/references/validations.md`
+
+| Validación | export-arq | export-scripts |
+|---|---|---|
+| V1 | estructura de secciones por `--scope` | estructura del bundle (archivos + sub-dirs) |
+| V2 | noise interno (~25 términos) | noise + placeholders (~45 términos) |
+| V3 | secciones por scope | 10 secciones fijas del manifest |
+| V4 | Modelo de datos + Decisiones condicionales | Vista por tema + code-scan skip + sesiones abiertas |
+| V5 | header con snapshot + fuentes + diagrams engine | header con rama + readiness + counts |
+| V6 | referencias resolubles | referencias resolubles |

package/skills/agent-workflow/exports/export-tech-manuals/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: export-tech-manuals
+description: "Genera y mantiene manuales técnicos del workspace en `docs/manuales/` consolidando sesiones + `docs/` (manuales/, decisiones/, especificaciones/ como referencias técnicas). Dos modos: `complementar` (default, sobrescribe `INDEX.md` apuntando a manuales graduados + detectables del corpus) y `regenerar` (produce dossier `NNN-export-tech-manuals-YYYY-MM-DD/` con 1 manual por tema detectado). Audiencia: operadores / soporte / onboarding. Read-only sobre corpus + `docs/manuales/` existente; sin commits autónomos. Invocado sólo vía `/agent-workflow:export-tech-manuals`. v1.1 (session081): corpus extendido formalmente a `docs/` además de sesiones (DEC-002) — ver `docs/shared-contract/export-corpus-sources.md`."
+version: 1.1.0
+---
+
+# Export Tech Manuals — Manuales técnicos desde corpus + graduados
+
+Tercer comando de la familia `/agent-workflow:export-*`. Genera un índice consolidado de manuales (modo default `complementar`) o un dossier completo con manuales sintetizados (modo `regenerar`). **Read-only / reporte** — no commitea, no muta nada del corpus.
+
+> Propuesta original: `docs/conclusiones/007-export-commands-family.md` §1.3. Pattern hermano: `agent-workflow/skills/export-arq/`.
+
+## Excepción session-aware
+
+Este skill requiere conocimiento del lifecycle. **No crea ni modifica sesiones**. Si el workspace no tiene AW-PROJECT con fuentes declaradas → abortar con `ok: false`.
+
+**Consumo de CLI `agent-workflow`** (no leer paths hardcodeados):
+- `agent-workflow project-md-upsert --read` — `workspace_mode`, fuentes.
+- `agent-workflow history-data` — sesiones cerradas para detectar temas/manuales no graduados.
+- `agent-workflow session-artifacts --code <NNN>` — OBJECTIVE + CHECKPOINT + (MANUAL.md si existe) por sesión.
+- `agent-workflow next-number docs/manuales` — sólo modo `regenerar`.
+
+**Lectura del filesystem**:
+- `docs/manuales/*.md` — manuales ya graduados (`kind=manual`).
+- `docs/manuales/INDEX.md` — sobrescribible (re-generable) en modo `complementar`.
+
+## When to use
+
+- "Manual operativo", "índice de manuales", "consolidar guías técnicas".
+- Tras agregar manuales nuevos via `agent-workflow graduate --kind manual`, refrescar el índice.
+- Paquete de onboarding técnico para nuevos miembros del equipo.
+- Auditoría de cobertura documental.
+
+## Qué hace este skill
+
+1. Lee AW-PROJECT (fuentes + mode).
+2. Lee `docs/manuales/*.md` (manuales graduados).
+3. Escanea corpus de sesiones cerradas detectando temas / manuales no graduados.
+4. Resuelve modo (`complementar` o `regenerar`).
+5. Aplica filtros `--since`, `--source`, `--temas` si están presentes.
+6. Carga plantilla (`template-index.md` o `template-manual.md`).
+7. Renderiza output aplicando léxico técnico mínimo.
+8. Valida V1-V6 (`references/validations.md`).
+9. Si pasa:
+   - `complementar`: sobrescribe `docs/manuales/INDEX.md`.
+   - `regenerar`: escribe `docs/manuales/NNN-export-tech-manuals-YYYY-MM-DD/` con 1 manual por tema.
+
+## Qué NO hace
+
+- Ejecutar commits, merges, push, SQL ni envío de correos.
+- Mutar manuales ya graduados (sólo los lee).
+- Mutar corpus de sesiones.
+- Sobrescribir un dossier `regenerar` previo (siempre next-number).
+- Renderizar visualmente diagramas (los manuales son texto; Mermaid embebido si aporta, pero no es obligatorio).
+- Inventar manuales: si no hay tema detectable, abortar con error claro en modo `regenerar`; en modo `complementar` produce INDEX vacío con nota inline.
+
+## Sandbox read-only
+
+`../session/references/sandbox-readonly-rules.md`. En plan mode esta skill describe:
+- Modo resuelto + plantilla a cargar.
+- Manuales graduados detectados (lista).
+- Temas detectables del corpus (lista + confidence).
+- Modo `regenerar`: count de manuales que se generarían.
+- Modo `complementar`: estructura del INDEX que se sobrescribiría.
+
+NO ejecuta: `Write` del INDEX o de los manuales, `agent-workflow next-number` con efecto, mutaciones.
+
+## Estilo de comunicación
+
+`../session/references/communication-style.md`. La audiencia es técnica — sin léxico ejecutivo. `agent-workflow:redaccion-simple` aplica con preset default. Foco en accionabilidad: cada manual debe permitir al operador completar la tarea sin invocar al equipo de desarrollo.
+
+## Entrada
+
+```
+/agent-workflow:export-tech-manuals [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]
+                          [--mode complementar|regenerar]
+                          [--temas slug1,slug2]
+                          [--dry-run]
+```
+
+### Defaults
+
+- `--mode complementar`.
+- Sin `--sessions` (todo el corpus).
+- Sin `--since` (todo el corpus). Ignorado si `--sessions` presente.
+- Sin `--source` (hub completo).
+- Sin `--temas` (todos los temas detectables).
+
+Ejemplo: `/agent-workflow:export-tech-manuals --sessions 055,057,061` consolida sólo esas 3 sesiones.
+
+### Resolución de `--mode`
+
+| Modo | Output | Cuándo usar |
+|---|---|---|
+| `complementar` (default) | `docs/manuales/INDEX.md` (sobrescribe) | Refresh del índice tras agregar manuales graduados |
+| `regenerar` | `docs/manuales/NNN-export-tech-manuals-YYYY-MM-DD/` (next-number) | Paquete consolidado de manuales (ej. onboarding) |
+
+### Detección de temas
+
+- **Fuente primaria**: `## Topics` o `## Temas` en OBJECTIVE.md de las sesiones del corpus.
+- **Fuente secundaria**: inferencia por keywords en OBJECTIVE/CHECKPOINT (confidence > 0.6).
+- **Override explícito**: `--temas slug1,slug2` limita a los slugs declarados.
+
+## Flujo
+
+### Paso 1 — Resolver contexto
+
+```
+agent-workflow project-md-upsert --read
+```
+
+Extrae `workspace_mode`, `fuentes[]`, `mode`. Determina root del workspace + path destino:
+- `hub` → `<hub>/docs/manuales/`.
+- `project` → `<cwd>/docs/manuales/`.
+
+### Paso 2 — Inspeccionar manuales graduados
+
+Listar `docs/manuales/*.md` (excluyendo `INDEX.md` y subdirectorios `NNN-export-tech-manuals-*/`).
+
+Para cada manual graduado, extraer:
+- Slug (del filename `NNN-<slug>.md`).
+- Título (primer `# ` header).
+- Resumen breve (primer párrafo, ≤200 caracteres).
+- Path canónico.
+
+### Paso 3 — Detectar temas/manuales no graduados
+
+```
+agent-workflow history-data
+```
+
+Para cada sesión cerrada del corpus filtrado por `--since` / `--source`:
+
+```
+agent-workflow session-artifacts --code <CODE>
+```
+
+Buscar:
+- Sección `## Topics` / `## Temas` en OBJECTIVE.md → slug declarado.
+- Archivo `MANUAL.md` dentro de la sesión (si existe).
+- Keywords operativos en OBJECTIVE/CHECKPOINT que sugieran un manual: "configurar", "instalar", "wizard", "paso a paso", "cómo hacer", etc.
+
+Listar temas detectados con (slug, confidence, sesiones de origen).
+
+Filtrar por `--temas slug1,slug2` si está presente.
+
+### Paso 4 — Resolver modo
+
+| Modo | Acción |
+|---|---|
+| `complementar` | Cargar `references/template-index.md` |
+| `regenerar` | Cargar `references/template-manual.md` |
+
+### Paso 5 — Renderizar
+
+**Modo `complementar`**:
+- Cabecera: título + count de manuales totales (graduados + detectables).
+- Tabla principal con columnas: Tema · Slug · Manual graduado (path o `[no graduado]`) · Sesiones de origen.
+- Sección "Próximos pasos sugeridos" si hay temas con `[no graduado]`.
+
+**Modo `regenerar`**:
+- 1 archivo `.md` por tema en el dossier.
+- Cada archivo sigue `template-manual.md`: Propósito · Pre-requisitos · Pasos numerados · Validación post-uso · Troubleshooting · Referencias.
+- `README.md` del dossier con índice de manuales generados.
+
+Aplicar `references/lexico-tecnico.md` durante el render (limpieza de noise).
+
+### Paso 6 — Validar (V1-V6)
+
+`references/validations.md`. Reglas adaptadas a los 2 modos:
+- V1 estructura por modo (INDEX con tabla principal vs dossier con N manuales completos).
+- V2 noise vetado.
+- V3 secciones de `template-manual.md` (sólo modo `regenerar`).
+- V4 condicionales (modo `regenerar` con 0 temas → abort; modo `complementar` con 0 manuales → INDEX con nota).
+- V5 header.
+- V6 referencias resolubles (paths a manuales graduados).
+
+Si V1, V3 o V4 fallan → abortar.
+
+### Paso 7 — Escribir output
+
+Si `--dry-run`: imprimir reporte. No escribir.
+
+Si pasa:
+- `complementar`: `Write` sobre `docs/manuales/INDEX.md` (sobrescribe).
+- `regenerar`: `agent-workflow next-number docs/manuales` → crear directorio + N archivos.
+
+### Paso 8 — Resumen al usuario
+
+- Modo + paths escritos.
+- Counts: manuales graduados detectados, temas no graduados detectables, manuales generados (modo `regenerar`).
+- Warnings: V5/V6 si emitieron.
+- Sugerencia: si hay temas detectables sin graduar, sugerir abrir sesiones dedicadas para producirlos formalmente.
+
+## Composición con otras skills
+
+- **`agent-workflow:redaccion-simple`** — preset default aplicado durante el render.
+- **`agent-workflow:rules`** — anchors transversales consultables.
+- **`session`** — este skill NO invoca graduación ni cierre. Una sesión activa puede consumirlo durante validation/closure para refrescar INDEX tras graduar un nuevo manual.
+
+## Re-ejecución
+
+- Modo `complementar`: idempotente — sobrescribe `INDEX.md`; dos invocaciones consecutivas con mismo corpus producen el mismo archivo.
+- Modo `regenerar`: cada invocación toma siguiente NNN. No sobrescribe dossiers previos.
+
+## Recursos adicionales
+
+- **`references/template-manual.md`** — estructura uniforme por manual (modo `regenerar`).
+- **`references/template-index.md`** — estructura del `INDEX.md` consolidado (modo `complementar`).
+- **`references/lexico-tecnico.md`** — noise mínimo vetado (idéntico patrón que export-arq).
+- **`references/validations.md`** — V1-V6 con reglas por modo.
+- **`docs/conclusiones/007-export-commands-family.md`** — Propuesta original (familia `/agent-workflow:export-*`).
+- **`agent-workflow/skills/export-arq/SKILL.md`** — hermano (arquitectura técnica).
+- **`agent-workflow/skills/export-report/SKILL.md`** — hermano (informe ejecutivo).