@tacuchi/agent-workflow-cli 9.3.0 → 10.1.0

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

@@ -1,79 +1,289 @@
-# Plantilla — README del bundle export-scripts
+# Plantilla — README del bundle export-scripts (v4.0.0)
 
-Plantilla exacta para el `README.md` del output dir. Se escribe junto con `manifest.md`. Reemplazar `[entre corchetes]` con valores reales.
+Plantilla canónica del `README.md` único del bundle. Reemplaza `manifest.md` + `ORDER.md` legacy desde v4.0.0 (session093). Reemplazar `[entre corchetes]` con valores reales al momento de generar.
+
+> **Heredada y consolidada de**: `manifest-template.md` v3.x (informe) + `readme-template.md` v3.x (índice). v4.0.0 unifica ambos en una sola plantilla siguiendo la doctrina "un solo punto de verdad" del usuario.
 
 ---
 
 ```markdown
 # Bundle export-scripts NNN — [YYYY-MM-DD]
 
-Bundle SQL + informe consolidado para paso a producción. Generado por `/agent-workflow:export-scripts`.
+- **Rama actual:** `[nombre-rama]`
+- **Rama destino:** `certificacion`
+- **Sesiones incluidas:** [N]
+- **Readiness:** [🟢 verde | 🟡 amarillo | 🔴 rojo]
+- **Generado por:** agent-workflow · skill `export-scripts` v4.0.0
 
-## Contenido
+## Contenido del bundle (layout v4.0.0)
 
-| Archivo | Propósito |
-|---|---|
-| `manifest.md` | Informe consolidado: sesiones, acciones manuales, BD, hallazgos code-scan, git state, checklist final. |
-| `ORDER.md` | Secuencia ejecutable cross-bundle (01 → 02 → 03 → 04 por sesión, intercalado por tema si aplica). |
-| `rollback-global.sql` | Rollback encadenado inverso (toda sesión → primera, 04 → 01 dentro de cada una). |
-| `por-sesion/` | Bundle SQL por sesión, organizado en 4 categorías. |
-| `por-tema/` | (opcional) Bundle consolidado cross-session por tema/funcionalidad. |
+| Archivo | Propósito | Condicional |
+|---|---|---|
+| `00-ROLLBACK.sql` | Único rollback cross-session — encadenado 04→01 dentro de un `BEGIN; ... COMMIT;` único. Bloque "Fase 5 — Cleanup irreversible" al final fuera de la transacción. | Siempre (si hay sentencias) |
+| `01-DDL-TABLES.sql` | `CREATE TABLE` / `ALTER TABLE` / `CREATE INDEX` / `CREATE SEQUENCE` cross-session. | Skip si categoría vacía |
+| `02-DDL-FUNCTIONS.sql` | `CREATE OR REPLACE FUNCTION` / `PROCEDURE` cross-session. | Skip si categoría vacía |
+| `03-DML.sql` | `UPDATE` / `DELETE` / migración de datos cross-session (con backup en `esq_audit` cuando aplica). | Skip si categoría vacía |
+| `04-INSERTS.sql` | `INSERT` / seed de datos maestros cross-session. | Skip si categoría vacía |
+| `README.md` | Este archivo — único informe + índice + how-to-execute. | Siempre |
+| `_queries/sessionXXX/` | Queries de consulta de soporte por sesión (no ejecución). | Solo si alguna sesión tenía `queries/` |
+| `por-tema/<slug>/` | Capa adicional opt-in con consolidado per-tema (sin rollback duplicado). | Solo si `--themes` activado o `## Temas` declarado |
 
-## Mapping sesión ↔ tema ↔ scripts
+---
 
-> **Condicional**: incluir esta sección **sólo si** `por-tema/` se generó.
+## 1. Resumen ejecutivo
 
-| Sesión | Tema | Scripts |
-|---|---|---|
-| session001 | `tema-rbac` | `01-rol-permiso.sql`, `02-fn-validacion.sql`, `03-mig-roles.sql` |
-| session002 | `tema-rbac` | `01-asignacion-default.sql` |
-| session003 | `tema-lista-negra-blanca` | `01-listas-table.sql`, `04-inserts-iniciales.sql` |
+[1-2 párrafos sintetizando qué entra en este bundle: módulos tocados, tipo de cambios predominantes (features, fixes, migración de datos), y el juicio general de readiness con 1-2 motivos principales.]
+
+**Motivos del color de readiness:**
+- [motivo 1]
+- [motivo 2]
+
+---
+
+## 2. Sesiones incluidas
+
+| # | Sesión | Estado | Fase | Fechas | Resumen | Refs |
+|---|---|---|---|---|---|---|
+| 1 | session001-nombre | closed | 5 | YYYY-MM-DD → YYYY-MM-DD | [resumen 1 línea] | [DEC](../decisiones/001-*.md) |
+| 2 | session002-nombre | ⚠ active | 3 | YYYY-MM-DD → — | [resumen 1 línea] + motivo de apertura | — |
+
+**Sesiones abiertas:** destacadas con ⚠. Cada una baja la readiness del bundle. Motivo y próxima acción debe quedar explícito en el resumen.
+
+---
+
+## 3. Acciones manuales previas a producción
 
-## Cómo ejecutar el bundle
+Checklist ordenado. Marcar cada ítem antes del despliegue.
 
-### Paso 1 — Validar pre-condiciones
+- [ ] **ACT-001** — [Título corto]
+  - **Motivo:** [por qué es necesaria]
+  - **Quién:** [rol/persona sugerida]
+  - **Detalle:** [qué hacer, con qué entrada/salida esperada]
 
-1. Revisar `manifest.md` §3 (acciones manuales) — completar antes de ejecutar SQL.
-2. Revisar `manifest.md` §5 (hallazgos code-scan) — resolver severidades altas.
-3. Tomar respaldo completo del esquema afectado.
+- [ ] **ACT-002** — Solicitar API keys de producción
+  - **Motivo:** REQUIREMENTS de session003 menciona integración con servicio externo pero no hay claves concretas.
+  - **Quién:** Administrador de infraestructura
+  - **Detalle:** enviar correo con plantilla en §3.1.
+
+### 3.1 Plantillas de correo
+
+Copiar, personalizar y enviar manualmente. **Este plugin no envía correos.**
+
+```
+Para: [correo-destino]
+CC: [correo-cc]
+Asunto: [Bundle NNN] Solicitud de API keys de producción
+
+Buen día,
+
+Para el bundle NNN-[nombre] que se despliega el [fecha objetivo] requerimos las siguientes credenciales de producción:
+
+- [servicio 1] — URL y token de acceso
+- [servicio 2] — usuario/clave técnica
+
+Adjunto el bundle: docs/scripts/NNN-export-scripts-[YYYY-MM-DD]/README.md
+
+Quedamos atentos.
+Saludos.
+```
+
+---
 
-### Paso 2 — Ejecutar SQL
+## 4. Secuencia de ejecución (01 → 04)
+
+Orden obligatorio. Categorías vacías se omiten (no aparece el archivo).
 
 ```bash
-# Opción A: orden por sesión (default)
-cat ORDER.md  # ver secuencia
+# 1. DDL de tablas (CREATE/ALTER TABLE, INDEX, SEQUENCE)
+psql -h <host> -U <user> -d <db> -f 01-DDL-TABLES.sql
+
+# 2. DDL de funciones (CREATE OR REPLACE FUNCTION/PROCEDURE)
+psql -h <host> -U <user> -d <db> -f 02-DDL-FUNCTIONS.sql
+
+# 3. DML / migración (UPDATE, DELETE, backup en esq_audit)
+psql -h <host> -U <user> -d <db> -f 03-DML.sql
 
-# Ejecutar manualmente cada script en orden:
-psql -h <host> -U <user> -d <db> -f por-sesion/session001-<slug>/01-ddl-tablas/001-*.sql
-# ... continuar con 02, 03, 04 ...
+# 4. Inserts / seed maestros
+psql -h <host> -U <user> -d <db> -f 04-INSERTS.sql
 ```
 
 > **Importante**: este plugin NO ejecuta SQL. El usuario aplica los scripts manualmente.
 
-### Paso 3 — Validar post-ejecución
+### 4.1 Mapping sesión ↔ tema ↔ scripts
 
-1. Marcar checklist final de `manifest.md` §8.
-2. Si algo falló: aplicar `rollback-global.sql` en una sola transacción.
+> **Condicional**: incluir esta sub-sección **sólo si** `--themes` activado y `por-tema/` se generó. Si no, omitir entera la 4.1.
 
-## Rollback
+| Sesión | Tema | Sentencias (categoría:NNN-stmt) |
+|---|---|---|
+| session001 | `tema-rbac` | 01:001-rol-permiso, 02:001-fn-validacion, 03:001-mig-roles |
+| session002 | `tema-rbac` | 01:001-asignacion-default |
+| session003 | `tema-lista-negra-blanca` | 01:001-listas-table, 04:001-inserts-iniciales |
 
-Bundle global: `rollback-global.sql` (este directorio).
+---
 
-Orden inverso absoluto: última sesión → primera; dentro de cada una 04 → 03 → 02 → 01.
+## 5. Rollback (`00-ROLLBACK.sql`)
 
-**Operaciones irreversibles** (si las hay): listadas en `manifest.md` §4.2 con su mitigación. Revisar antes de ejecutar rollback.
+Un solo archivo cross-session al root del bundle. Orden interno inverso absoluto: última sesión → primera; dentro de cada una 04 → 03 → 02 → 01.
 
-## Re-generación
+```bash
+# Ejecutar el rollback completo en una sola transacción:
+psql -h <host> -U <user> -d <db> -f 00-ROLLBACK.sql
+```
 
-Para regenerar este bundle:
+### 5.1 Operaciones irreversibles
+
+**Detectadas en el bundle:**
+
+| Sesión origen | Operación | Mitigación disponible |
+|---|---|---|
+| session003 | `DROP COLUMN col_legacy` | Respaldo previo en `esq_audit.tb_bkp_session003` (incluido en `03-DML.sql`) |
+| session005 | `TRUNCATE esq_x.tb_z` | Sin backup automático — pérdida total de datos |
+
+Si no hay irreversibles: incluir un placeholder con "Sin operaciones irreversibles en este bundle." (el AI debe reemplazar la tabla por esta frase única).
+
+**Bloque "Fase 5" del `00-ROLLBACK.sql`**: las operaciones irreversibles aparecen al final del archivo **fuera de la transacción** principal, con header `-- WARNING: IRREVERSIBLE` y referencia a la DECISION de la sesión origen. El operador decide ejecutar este bloque manualmente.
+
+### 5.2 Impacto
+
+- **Tablas creadas:** [lista]
+- **Tablas modificadas:** [lista, indicando tipo de ALTER]
+- **Funciones creadas/modificadas:** [lista]
+- **Filas afectadas por migración:** [estimación si hay count en sesiones]
+
+---
+
+## 6. Código fuente — hallazgos del escaneo
+
+> **Condicional V4.b**: si `--skip-code-scan` fue usado, esta sección contiene **sólo** una nota inline `_(Escaneo omitido por --skip-code-scan)_` y nada más.
+
+**Resumen:** [X] críticos · [Y] medios · [Z] bajos
+
+### 6.1 Severidad alta (bloqueantes para producción)
+
+| # | Patrón | Archivo:línea | Snippet | Recomendación |
+|---|---|---|---|---|
+| H1 | Credencial hardcodeada | `src/.../Config.java:42` | `password = "..."` | Mover a variable de entorno o gestor de secretos. Rotar la credencial si fue commiteada. |
+
+Si vacío: incluir un placeholder con "Sin hallazgos de severidad alta." (frase única que reemplaza la tabla).
+
+### 6.2 Severidad media
+
+| # | Patrón | Archivo:línea | Snippet | Recomendación |
+|---|---|---|---|---|
+| M1 | URL localhost | `src/.../api.service.ts:18` | `http://localhost:8080` | Reemplazar por `environment.apiUrl` u otro mecanismo de configuración. |
+
+### 6.3 Severidad baja
+
+Agrupados por patrón, con conteo.
+
+| Patrón | Conteo | Ejemplos |
+|---|---|---|
+| `TODO` | 7 | `UserService.java:88`, `OrderService.java:42`, ... |
+| `FIXME` | 2 | `validator.ts:15`, `payment.ts:103` |
+
+### 6.4 Alcance del escaneo
+
+- **Directorios incluidos:** [lista]
+- **Directorios excluidos:** `node_modules/`, `target/`, `dist/`, `build/`, `.workflow/`, `docs/`, `tests/`, `test/`, `.git/`
+- **Extensiones:** [lista]
+
+---
+
+## 7. Git y ramas
+
+- **Rama actual:** `[nombre]`
+- **Rama destino:** `certificacion`
+- **Commits pendientes de merge (rama actual → certificacion):** [N]
+
+### 7.1 Commits pendientes
 
 ```
-/agent-workflow:export-scripts [--since sessionNNN] [--themes slug1,slug2]
+[sha corto] [mensaje]
+[sha corto] [mensaje]
 ```
 
-Cada invocación toma siguiente NNN. NO sobrescribe bundles previos.
+### 7.2 Archivos modificados (git diff --stat)
 
-## Relación con release legacy
+```
+[salida de git diff certificacion --stat]
+```
+
+### 7.3 Cambios sin commitear
+
+Si `git status` muestra archivos modificados/untracked:
+
+```
+[salida de git status --porcelain]
+```
+
+**Acción recomendada:** el usuario decide si esos cambios entran al bundle (commit) o no (stash/descartar).
+
+### 7.4 PR sugerido (texto — no se crea)
+
+```
+Título: [feat/fix/chore]: [resumen del bundle]
+Rama origen: [rama actual]
+Rama destino: certificacion
+Descripción:
+- Bundle NNN consolidando las siguientes sesiones:
+  - session001 — [título]
+  - session002 — [título]
+- Bundle completo: docs/scripts/NNN-export-scripts-[YYYY-MM-DD]/
+```
+
+---
+
+## 8. Documentación graduada
+
+| Sesión | Decisiones | Manuales | Especificaciones | Conclusiones |
+|---|---|---|---|---|
+| session001 | `001-*.md`, `002-*.md` | — | — | — |
+| session002 | — | `003-*.md` | — | — |
+| session003 | `004-*.md` | — | `001-*/` | — |
+
+Nota: el modelo nuevo gradua 6 kinds (`decision`, `manual`, `script`, `especificacion`, `conclusion`, `release`). Este README enlaza los 4 primeros; `release` queda implícito en este mismo dossier; `script` queda implícito en los archivos `0X-*.sql` del root.
+
+---
+
+## 9. Checklist final de producción
+
+Lista única consolidada. Todos los ítems deben marcarse antes del "go":
+
+- [ ] **BD:** respaldo completo del esquema afectado tomado y verificado
+- [ ] **BD:** scripts ejecutados en orden (`01-DDL-TABLES.sql` → `02-DDL-FUNCTIONS.sql` → `03-DML.sql` → `04-INSERTS.sql`)
+- [ ] **BD:** `00-ROLLBACK.sql` probado en staging/certificación
+- [ ] **Infra:** variables de entorno actualizadas (ver §3)
+- [ ] **Infra:** API keys de producción solicitadas y configuradas
+- [ ] **Código:** hallazgos de severidad alta resueltos (§6.1)
+- [ ] **Git:** rama mergeada a `certificacion` (o PR aprobado)
+- [ ] **Git:** tag/release creado en el repositorio
+- [ ] **Stakeholders:** notificación enviada antes y después del despliegue
+- [ ] **Acciones manuales:** todos los ACT-XXX de §3 completados
+
+### 9.1 Advertencias
+
+Cosas que el skill detectó pero no pudo validar automáticamente. Leer antes de marcar el checklist como completo.
+
+Si no hay advertencias: incluir un placeholder con "Sin advertencias pendientes." (frase única).
+
+---
+
+## 10. Metadata
+
+- **Generado:** YYYY-MM-DD HH:MM
+- **Versión del skill:** export-scripts v4.0.0 (layout plano cross-session)
+- **Sub-skill rollback:** sql-rollback-generator v2.0.0
+- **Argumentos usados:** `[sin argumentos | --sessions NNN[,NNN] | --since sessionNNN | --themes slug1,slug2 | --dry-run | --skip-code-scan]`
+- **Comando original:** `/agent-workflow:export-scripts [args]`
+- **Reemplaza:** `/agent-workflow:release` v2.0.0 + `/agent-workflow:release-scripts` v2.0.0 (ambos en deprecation Fase 1 desde plugin v2.8.0)
+
+## Re-generación
+
+Para regenerar este bundle:
+
+```
+/agent-workflow:export-scripts [--sessions NNN[,NNN]] [--since sessionNNN] [--themes slug1,slug2]
+```
 
-Este bundle reemplaza el output que generaban `/agent-workflow:release` + `/agent-workflow:release-scripts` legacy (ambos en deprecation Fase 1 desde plugin v2.8.0). Si tu workspace tiene `docs/release/` poblado: queda como histórico, no se migra.
+Cada invocación toma siguiente NNN. NO sobrescribe bundles previos. Bundles generados con export-scripts v3.x (layout `por-sesion/` + `manifest.md` + `ORDER.md` + `rollback-global.sql`) quedan como histórico y no se migran.
 ```

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

@@ -1,16 +1,16 @@
-# Theme handling — detección + consolidación + ORDER cross-tema
+# Theme handling — detección + consolidación per-tema (v4.0.0)
 
-> **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.
+> **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 layout plano de export-scripts v4.0.0. **session093**: la capa `por-tema/` ya NO duplica el rollback y NO emite `ORDER.md` separado — el rollback canónico es `00-ROLLBACK.sql` único al root, y la secuencia de ejecución vive en §4 del `README.md`.
 
-## Activación de la vista `por-tema/`
+## Activación de la capa `por-tema/`
 
-`por-tema/` se genera **sólo** si se cumple **alguna** de estas condiciones:
+`por-tema/` es **capa adicional opt-in encima del root plano** — NO reemplaza los archivos `0X-*.sql` consolidados cross-session al root. 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.
+Si **ninguna** se cumple: el output dir contiene sólo `00-ROLLBACK.sql` + `0X-*.sql` (categorías con contenido) + `README.md` al root. No se crea sub-carpeta `por-tema/` vacía.
 
 ## Formato de `## Temas` en OBJECTIVE
 
@@ -37,12 +37,12 @@ Para cada sesión incluida, leer `OBJECTIVE.md` (fallback bilingual a `OBJETIVO.
 
 Para cada sesión sin `## Temas`:
 
-1. Leer OBJECTIVE + nombres de scripts SQL.
+1. Leer OBJECTIVE + sentencias del `SCRIPTS.sql` (con sus markers `@objeto`).
 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: `export-report` (confidence 0.92, sentencias: ...)
    - Tema candidato: `lifecycle-extension` (confidence 0.45)
    - ¿Aceptar / editar / declarar uno propio?
    ```
@@ -52,112 +52,85 @@ Para cada sesión sin `## Temas`:
 
 ### 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/`).
+Si `--themes slug1,slug2` declarado: restringir el output `por-tema/` a esos slugs. Sentencias cuyo tema no entre en el filtro **siguen apareciendo en los archivos `0X-*.sql` del root** (la consolidación cross-session es independiente del filtro de temas) pero no se replican en `por-tema/`.
 
-## Asignación de cada script a su tema
+## Asignación de cada sentencia a su tema
 
-Por cada `.sql` forward de las sesiones incluidas:
+Por cada sentencia forward parseada del `SCRIPTS.sql` (markers `@category` + `@stmt`):
 
-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.
+1. **Header declarativo**: leer marker `-- Temas: slug1, slug2` si está presente. Si sí: usar esos slugs.
+2. **Por nombre del stmt**: matchear contra patrones del tema (substring del slug en el nombre `@stmt`, ej. `rbac-rol-permiso` → `rbac`).
+3. **Por contenido**: leer el cuerpo de la sentencia 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 `README.md` §1.
 
 ### 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:
+Si una sentencia 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
+# Link — sentencia multi-tema
 
-Este script aplica al tema `[secundario]` pero su versión canónica vive en:
+Esta sentencia 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]`)
+- `por-tema/tema-[primario]/03-DML.sql` (sección [N], sentencia `[stmt-original]`)
 
-Razón: el header declarativo del script lista temas múltiples, y por convención el primero es el canónico.
+Razón: el marker `-- Temas:` 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.
+1. Ordenar sentencias fuente por orden cronológico (cross-session por sNNN → orden de aparición en SCRIPTS.sql).
+2. Para cada sentencia, extraer cuerpo eliminando `BEGIN;` inicial y `COMMIT;` final.
+3. Concatenar con separadores `[i/N]` + nombre `@stmt` + ruta canónica al `SCRIPTS.sql` original.
 4. Envolver todo en un único `BEGIN; … COMMIT;`.
-5. Escribir `por-tema/tema-<slug>/<categoria>.sql`.
-6. Consolidar `.rollback.sql` en orden inverso.
+5. Escribir `por-tema/tema-<slug>/<categoria>.sql` con nombres UPPERCASE EN canon: `01-DDL-TABLES.sql`, `02-DDL-FUNCTIONS.sql`, `03-DML.sql`, `04-INSERTS.sql`.
+6. **NO se genera** `<tema>/rollback*` ni `<tema>/00-ROLLBACK.sql`. El rollback canónico es `<bundle-root>/00-ROLLBACK.sql` único — un solo punto de verdad para reversa.
 
 ### 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
+-- ============================================================================
+-- Script:  tema-rbac/03-DML.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`.
+**No copiar** los headers individuales de cada sentencia — su origen queda registrado en los separadores `[i/N]` del cuerpo y en `README.md` §4.1 (mapping cuando `por-tema/` activo).
 
 ### `--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.
+Si el flag está activo: preservar `por-tema/<slug>/parts/<categoria>/*.sql` con sentencias individuales (no consolidadas). Permite ejecutar una por vez para debugging.
 
-## Rollback por tema y global
+## Rollback con temas activos
 
-### `por-tema/tema-<slug>/rollback-tema-<slug>.sql`
+Sigue siendo **único**: `<bundle-root>/00-ROLLBACK.sql` cubre todas las sentencias del corpus, indistinto del tema. Cuando `por-tema/` está activo, el `README.md` §5 incluye una nota explícita:
 
-Encadena los 4 consolidados de rollback (04→03→02→01) dentro de un único `BEGIN; … COMMIT;`. Operaciones irreversibles marcadas con header WARNING.
+> El `00-ROLLBACK.sql` revierte todos los temas. NO ejecutar rollbacks parciales por tema — dejaría el estado de BD inconsistente cuando los temas comparten objetos (tablas, funciones, foreign keys).
 
-### `rollback-global.sql` (en output dir top-level)
+Algoritmo de generación del `00-ROLLBACK.sql` en `sql-rollback-generator/SKILL.md` v2.0.0.
 
-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.
+## Secuencia de ejecución cuando `por-tema/` está activo
 
-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):
+§4 del `README.md` incluye una variante "Por tema (opcional)" además del orden canónico al root. Ejemplo:
 
 ```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
+### 4.2 Ejecución per-tema (opcional, requiere --themes)
 
-...
+Útil cuando un solo tema necesita validarse aisladamente en staging antes del despliegue completo. **Importante**: si se ejecuta un tema parcial, el rollback canónico (`00-ROLLBACK.sql`) sigue cubriendo todo el bundle — no hay rollback per-tema.
 
-## Fase 5 — Cleanup irreversible
-
-(operaciones DROP COLUMN, TRUNCATE, DROP CASCADE — al final)
+```bash
+# Tema rbac:
+psql -f por-tema/tema-rbac/01-DDL-TABLES.sql
+psql -f por-tema/tema-rbac/02-DDL-FUNCTIONS.sql
+psql -f por-tema/tema-rbac/03-DML.sql
+psql -f por-tema/tema-rbac/04-INSERTS.sql
 ```
-
-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