@tacuchi/agent-workflow-cli 6.2.0 → 7.0.1

package/skills/agent-workflow/standards/sql-script-organizer/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: sql-script-organizer
+description: "Mantiene el archivo único SCRIPTS.sql por sesión (uppercase EN canon, F-D session062), aplica estilo del proyecto (BEGIN/COMMIT, idempotencia, schema explícito), markers @category (01-ddl-tablas, 02-ddl-funciones, 03-migracion, 04-inserts) y @stmt por sentencia. La separación 01-04 + generación de rollbacks ocurre post-hoc en /agent-workflow:export-scripts (no durante exec). BREAKING desde v1.0.0: reemplaza el layout scripts/01-04/* + .rollback.sql per archivo (2N+1) por SCRIPTS.sql único. Layouts legacy se migran con /agent-workflow:migrate --upgrade-topology."
+version: 1.0.0
+---
+
+# SQL Script Organizer
+
+Organización, estilo y graduación de scripts SQL dentro del flujo de sesiones.
+
+## Regla cero — read/write filesystem only
+
+Este skill **organiza, renumera, escribe diffs y prepara el bundle** en disco. **Nunca ejecuta SQL** contra `<mcp-cert>`/`<mcp-prod>` ni ningún otro destino. La aplicación del bundle (DDL, migraciones, inserts) la realiza el **usuario** manualmente, fuera del scope de este skill. Si durante el flujo aparece tentación de "verificar aplicando" — refusar y pedir al usuario que ejecute.
+
+## When to use
+
+- Cuando existan ≥2 archivos `.sql` en la sesión y necesiten ordenarse para entrega.
+- **Antes de escribir un nuevo `.sql`** — para elegir categoría correcta y aplicar estilo desde el inicio.
+- Al llegar a Fase 5 (Cierre) con scripts SQL pendientes de graduar.
+- NL: "unificar", "reorganizar", "preparar bundle de scripts", "listos para prod".
+- Al renumerar o reclasificar scripts durante la sesión.
+
+## Sandbox read-only
+
+`../session/references/sandbox-readonly-rules.md`. Plan describe clasificación, renumeración y orden propuestos (sin crear ni mover `.sql`).
+
+## Staging durante la sesión (v1.0.0 — BREAKING)
+
+**Archivo único** en la raíz de la sesión:
+
+```
+.workflow/sessions/sessionXXX-nombre/
+└── SCRIPTS.sql           (consolidado de todas las sentencias de la sesión)
+```
+
+Spec completa: ver [`references/scripts-sql-format.md`](references/scripts-sql-format.md).
+
+**Cada sentencia** se appendea al SCRIPTS.sql con un par de markers en comentarios:
+
+```sql
+-- @category: 01-ddl-tablas
+-- @stmt: 01-crear-tabla-usuarios
+CREATE TABLE IF NOT EXISTS esq_credito.tb_usuarios (
+  ...
+);
+```
+
+- `@category` clasifica la sentencia (4 valores canónicos, ver tabla abajo).
+- `@stmt` da el slug determinístico (`NN-verbo-objetivo`). Sirve para que `export-scripts` derive el filename al separar.
+- Orden cronológico dentro del archivo = orden en que se appendea. `export-scripts` resuelve el orden de ejecución final por categoría (01 → 02 → 03 → 04).
+- `BEGIN;` global al inicio del archivo, `COMMIT;` al final. Cada sentencia individual NO trae su propio BEGIN/COMMIT (la separación post-hoc los agrega por archivo).
+
+> **Sin .rollback.sql per archivo durante exec**. Los rollbacks se generan post-hoc al correr `/agent-workflow:export-scripts` (ver `sql-rollback-generator` v1.0.0).
+
+## Migración desde layout legacy
+
+Sesiones creadas con `sql-script-organizer` v0.x usan layout antiguo:
+
+```
+.workflow/sessions/sessionXXX-nombre/scripts/
+├── 01-ddl-tablas/
+│   └── 001-crear-tabla.sql
+├── 02-ddl-funciones/
+│   └── 001-crear-fn.sql
+└── ...
+```
+
+Para migrar: `/agent-workflow:migrate --upgrade-topology`. El skill `migrate` detecta el layout legacy y consolida en `SCRIPTS.sql` preservando order + agregando markers. Ver `agent-workflow/skills/migrate/SKILL.md` capability 11.
+
+`/agent-workflow:export-scripts` aborta si detecta layout legacy sin migrar. NO consume sesiones mixtas.
+
+## Las 4 categorías (markers `@category`)
+
+| Marker | Patrones de detección |
+|---|---|
+| `01-ddl-tablas` | `CREATE TABLE`, `DROP TABLE`, `ALTER TABLE`, `CREATE INDEX`, `CREATE SEQUENCE` |
+| `02-ddl-funciones` | `CREATE [OR REPLACE] FUNCTION`, `CREATE [OR REPLACE] PROCEDURE`, `DROP FUNCTION`, `DROP PROCEDURE` |
+| `03-migracion` | `UPDATE`, `INSERT ... SELECT ...`, `DELETE` sobre datos existentes, transformaciones de columnas |
+| `04-inserts` | `INSERT INTO ... VALUES`, seeds de catálogos, `tb_maestra_detalle`, datos de configuración inicial |
+
+**Orden de ejecución obligatorio**: 01 → 02 → 03 → 04. El archivo SCRIPTS.sql puede mezclar categorías cronológicamente; `export-scripts` ordena al bundle final.
+
+Patrones detallados y edge cases en `references/categorization-rules.md`.
+
+## Reglas de estilo SQL
+
+Cumplir `coding-standards/references/database-conventions.md#estilo-de-scripts-sql`:
+
+- `BEGIN;` al inicio, `COMMIT;` al final.
+- Idempotencia: `CREATE TABLE IF NOT EXISTS`, `DROP ... IF EXISTS`, `CREATE OR REPLACE`, `ON CONFLICT`.
+- Cuerpo: preferir `WITH ... AS` (CTEs encadenadas) sobre subqueries anidados y sobre `DO $$ ... LOOP ... END $$`. Ver "Cuerpo: CTEs sobre DO/LOOP" abajo.
+- Header canónico de 4 líneas (Script / Sesion / Objeto / Alcance). Ver "Header canónico" abajo.
+- Separador entre secciones: una línea de comentario envuelta por guiones. Ver "Separadores entre secciones" abajo.
+- Nunca crear `fn_*`/`sp_*` para reusar lógica exclusiva de un script; usar CTE o inline.
+- Schema siempre explícito (`esq_credito.tb_x`, nunca `public.`).
+
+### Header canónico
+
+Bloque único al inicio del script, entre dos líneas de iguales:
+
+```sql
+-- ============================================================================
+-- Script:  NNN-tipo-objetivo.sql
+-- Sesion:  sNNN
+-- Objeto:  <qué hace, 1-2 líneas>
+-- Alcance: <filtros y boundaries del cambio, 1 línea>
+-- ============================================================================
+```
+
+- Solo 4 campos: `Script`, `Sesion`, `Objeto`, `Alcance`.
+- `Sesion` puede listar varias sesiones cuando el script trazó historia (ej. `s078 → s080 (fix UNIQUE) → s082 (simplificado)`).
+- Autor / Fecha / "Defensa futura" / notas largas **NO** van dentro del header. Si el contexto lo amerita, van como bloque libre debajo del header (separado por una línea en blanco). Default: no se generan.
+- Si el motor no es Postgres, indicarlo en `Objeto:` o como nota libre debajo, no como campo del header.
+
+### Separadores entre secciones
+
+Cada sección del cuerpo se introduce con una línea de comentario corta envuelta por guiones seguidos:
+
+```sql
+-- ----------------------------------------------------------------------------
+-- N. Descripción corta de qué hace este bloque.
+-- ----------------------------------------------------------------------------
+```
+
+- Sin cajas dobles (`====` queda solo para el header).
+- Si el script tiene una sola sección, omitir separadores.
+- No partir un bloque corto solo por estética — los separadores marcan flujos lógicos, no líneas.
+
+### Cuerpo: CTEs sobre DO/LOOP
+
+- Default: una transformación = `WITH ... AS` con CTEs encadenadas + un `INSERT/UPDATE/DELETE` final que las consume.
+- Evitar `DO $$ DECLARE ... FOR ... LOOP ... END $$` cuando el mismo resultado se logra declarativamente. Es código que el lector tiene que mentalizar fila a fila; el SQL declarativo es más fácil de auditar y revertir.
+- Excepción permitida: descubrimiento dinámico de objetos (FKs, columnas, constraints, secuencias) que no se puede expresar en SQL declarativo. En ese caso documentar el motivo en `Objeto:` del header (ej. `Objeto: ... cascadea a hijas via FKs detectadas dinámicamente.`).
+
+## Proceso de mantenimiento del SCRIPTS.sql (v1.0.0)
+
+1. **Detectar la categoría** del cambio a aplicar siguiendo la tabla de markers.
+2. **Verificar idempotencia** del statement (CREATE OR REPLACE, IF EXISTS, ON CONFLICT, etc.).
+3. **Append** al `SCRIPTS.sql` con par de markers (`@category` + `@stmt`).
+4. **Style check** — el statement debe cumplir el header canónico, CTEs sobre DO/LOOP, schema explícito.
+5. **NO mover ni renumerar** archivos individuales (solo hay un SCRIPTS.sql).
+6. **NO generar `.rollback.sql`** durante exec (rollback se genera al exportar).
+
+El usuario revisa el SCRIPTS.sql periódicamente; la separación 01-04 final y la verificación de dependencias cruzadas la hace `/agent-workflow:export-scripts` post-hoc.
+
+## Layout del bundle (post-export-scripts v3.0.0)
+
+`/agent-workflow:export-scripts` produce el bundle al ejecutarse, no este skill:
+
+```
+<docs>/scripts/NNN-export-scripts-YYYY-MM-DD/por-sesion/sessionXXX-nombre/
+├── README.md                                  (generado por export-scripts)
+├── 01-ddl-tablas/
+│   ├── 001-crea-tb-x.sql                      (derivado de @stmt: 001-crea-tb-x)
+│   └── ...
+├── 02-ddl-funciones/
+├── 03-migracion/
+│   ├── 000-backup-tb-x.sql                    (auto-generado por sql-rollback-generator si UPDATE/DELETE masivo)
+│   └── ...
+├── 04-inserts/
+└── rollback/
+    ├── 00-rollback-global.sql                 (encadenado 04→03→02→01)
+    └── NNN-*.rollback.sql                     (1 por @stmt forward)
+```
+
+Layout **legacy** pre-v1.0.0 (`scripts/01-04/*.sql + .rollback.sql` directo en sesión) ya **no se genera**; sesiones nuevas usan SCRIPTS.sql. Layouts legacy en sesiones cerradas se migran con `/agent-workflow:migrate --upgrade-topology`.
+
+## Graduación al cierre (vía `/agent-workflow:release`)
+
+Los scripts viven en la sesión durante execution: `.workflow/sessions/<folder>/scripts/`. La graduación a `docs/scripts/NNN-sessionXXX-<slug>/` la hace **`/agent-workflow:release` exclusivamente** (DEC-003) — único disparador de `kind=script`. Sesiones individuales NO invocan `agent-workflow graduate --kind script` directamente.
+
+Destino al graduar (DEC-002, vía release):
+- **hub mode** → `<hub>/docs/scripts/NNN-sessionXXX-<slug>/`.
+- **project mode** → `<cwd>/docs/scripts/NNN-sessionXXX-<slug>/`.
+
+`NNN` = siguiente correlativo en `docs/scripts/` (`agent-workflow next-number docs/scripts`). Release registra la ruta en `.workflow/HISTORY.md`.
+
+## Modo release (cross-session + por tema)
+
+Cuando `release` o `release-scripts` invocan este skill, aplica modo consolidación cross-session o modo por tema. Ambos comparten la clasificación 01→04 pero cambian el layout y la transaccionalidad.
+
+Procedimiento completo (entrada, proceso paso a paso, layout destino, formato del consolidado, qué NO hacer) en **`references/consolidation-cross-session.md`**.
+
+## Integración con otros skills
+
+- **`sql-rollback-generator`** v1.0.0+ — **on-export**: ya NO genera rollbacks durante exec. La generación ocurre cuando `export-scripts` corre.
+- **`export-scripts`** v3.0.0+ — consume `SCRIPTS.sql` per sesión, separa en 01-04 y delega a `sql-rollback-generator` para los rollbacks. Aborta si detecta layout legacy.
+- **`migrate`** v1.3.0+ — capability 11: convierte layouts legacy `scripts/01-04/*.sql` → `SCRIPTS.sql` consolidado.
+- **`coding-standards`** — fuente de las reglas de estilo (`database-conventions.md`).
+- **`session`** — Fase execution invoca este skill al primer change SQL; Fase closure no necesita acción adicional.
+
+## Ejemplo de header simplificado
+
+Antes (estilo viejo, evitar):
+
+```sql
+-- ============================================================================
+-- Script: 020-dml-normalizar-codusuario-uppercase.sql
+-- Sesion: s078 (creado) → s079 (formato iniciales) → s080 (fix UNIQUE)
+-- Fecha:  2026-04-29
+-- Autor:  Jesus Loayza (con asistencia AI)
+-- Objeto: Renombra esq_x.tb_x.cod a MAYUSCULAS con sufijo numerico para
+--         colisiones internas. Cascadea a hijas via FKs detectadas dinamicamente.
+-- Alcance: SOLO usuarios id_tipo = 'CORE' con tb_persona valida.
+-- Defensa futura: AuthSvc.generarCod en mscore-mantenimiento.
+-- ============================================================================
+-- Si el INSERT al mapping rebota con UNIQUE, significa que ...
+-- ============================================================================
+```
+
+Después (estilo canónico):
+
+```sql
+-- ============================================================================
+-- Script:  020-dml-normalizar-codusuario-uppercase.sql
+-- Sesion:  s078 → s080 (fix UNIQUE) → s082 (simplificado one-shot, sin trigger)
+-- Objeto:  Renombra esq_x.tb_x.cod a MAYUSCULAS con sufijo numérico para
+--          colisiones. Cascadea a hijas vía FKs detectadas dinámicamente.
+-- Alcance: SOLO usuarios id_tipo = 'CORE' con tb_persona válida.
+-- ============================================================================
+```
+
+Y en el cuerpo, las secciones se separan así:
+
+```sql
+-- ----------------------------------------------------------------------------
+-- 1. Mapping old → new para CORE con persona válida.
+-- ----------------------------------------------------------------------------
+WITH bases AS (
+    SELECT u.id, u.cod AS old_code,
+           UPPER(LEFT(TRIM(p.nombres), 1) || REPLACE(TRIM(p.apellido_paterno), ' ', '')) AS base_code
+      FROM esq_x.tb_x u
+      JOIN esq_x.tb_persona p ON p.id_persona = u.id_persona
+     WHERE u.id_tipo = 'CORE'
+),
+mapped AS ( ... )
+INSERT INTO _cod_map (id, old_code, new_code) SELECT id, old_code, new_code FROM mapped;
+```
+
+## Recursos adicionales
+
+- **`references/categorization-rules.md`** — patrones detallados, edge cases, scripts mixtos.
+- **`references/bundle-readme-template.md`** — plantilla para `scripts/bundle/README.md`.
+- **`references/consolidation-cross-session.md`** — modo release (cross-session + por tema).

package/skills/agent-workflow/standards/sql-script-organizer/references/bundle-readme-template.md

@@ -0,0 +1,82 @@
+# Plantilla — README del Bundle SQL
+
+Usar esta plantilla para generar `scripts/bundle/README.md` al finalizar la reorganización.
+
+---
+
+```markdown
+# Bundle SQL — sessionXXX: [nombre de sesión]
+
+## Información
+
+- **Sesión:** sessionXXX-[nombre-kebab]
+- **Fecha de bundle:** YYYY-MM-DD
+- **Motor de BD:** PostgreSQL [versión si se conoce]
+- **Esquemas afectados:** esq_[dominio1], esq_[dominio2]
+
+## Resumen
+
+[1-2 líneas describiendo qué hace este bundle en conjunto]
+
+## Orden de ejecución (forward)
+
+Ejecutar en este orden exacto. Cada script usa `BEGIN`/`COMMIT`.
+
+### 01 — DDL de Tablas
+
+| # | Archivo | Descripción |
+|---|---|---|
+| 1 | `01-ddl-tablas/001-crea-tb-x.sql` | [descripción breve] |
+| 2 | `01-ddl-tablas/002-agrega-col-tb-y.sql` | [descripción breve] |
+
+### 02 — DDL de Funciones / SP
+
+| # | Archivo | Descripción |
+|---|---|---|
+| 1 | `02-ddl-funciones/001-crea-fn-z.sql` | [descripción breve] |
+
+### 03 — Migración de Datos
+
+> Ejecutar scripts de respaldo (`000-backup-*.sql`) primero.
+
+| # | Archivo | Descripción |
+|---|---|---|
+| 1 | `03-migracion/000-backup-tb-x.sql` | Respaldo previo en esq_audit |
+| 2 | `03-migracion/001-migra-estado-x.sql` | [descripción breve] |
+
+### 04 — Inserts Nuevos
+
+| # | Archivo | Descripción |
+|---|---|---|
+| 1 | `04-inserts/001-inserta-maestras.sql` | [descripción breve] |
+
+## Rollback
+
+Para revertir **toda** la sesión: ejecutar `rollback/00-rollback-global.sql`.
+
+Para revertir **un script específico**: ejecutar el `.rollback.sql` acoplado al lado del forward.
+
+**Orden de rollback** (inverso al forward): 04 → 03 → 02 → 01.
+
+## Operaciones irreversibles
+
+<!-- Listar si aplica. Si no hay ninguna, eliminar esta sección. -->
+
+| Script | Operación | Riesgo | Mitigation |
+|---|---|---|---|
+| `01-ddl-tablas/002-elimina-col-legacy.sql` | DROP COLUMN | Pérdida de datos | Backup en esq_audit antes de ejecutar |
+
+## Dependencias externas
+
+<!-- Scripts o estados de BD que deben existir ANTES de ejecutar este bundle -->
+
+- [Ej: `tb_maestra_detalle` debe tener el `codprog` X con los estados Y, Z]
+- [Ej: El feature flag `FLAG_NUEVA_FUNCIONALIDAD` debe estar activo]
+
+## Notas de ejecución
+
+<!-- Cualquier instrucción manual necesaria antes o después del bundle -->
+
+- [Ej: Detener el servicio X antes de ejecutar `03-migracion/`]
+- [Ej: Refrescar la caché de parámetros después de `04-inserts/`]
+```

package/skills/agent-workflow/standards/sql-script-organizer/references/categorization-rules.md

@@ -0,0 +1,122 @@
+# Reglas de Categorización de Scripts SQL
+
+## Patrones de detección por categoría
+
+### `01-ddl-tablas/` — Estructura de tablas
+
+| Patrón | Ejemplos |
+|---|---|
+| `CREATE TABLE` | `CREATE TABLE IF NOT EXISTS esq_credito.tb_solicitud (...)` |
+| `DROP TABLE` | `DROP TABLE IF EXISTS esq_credito.tb_solicitud_bkp;` |
+| `ALTER TABLE ... ADD COLUMN` | `ALTER TABLE esq_credito.tb_credito ADD COLUMN flag_activo integer;` |
+| `ALTER TABLE ... DROP COLUMN` | `ALTER TABLE esq_credito.tb_credito DROP COLUMN IF EXISTS col_legacy;` |
+| `ALTER TABLE ... ALTER COLUMN` | `ALTER TABLE tb_x ALTER COLUMN monto_total TYPE numeric(18,4);` |
+| `ALTER TABLE ... RENAME` | `ALTER TABLE esq_credito.tb_x RENAME COLUMN col_vieja TO col_nueva;` |
+| `CREATE INDEX` | `CREATE INDEX IF NOT EXISTS idx_tb_credito_cliente ON esq_credito.tb_credito(id_cliente);` |
+| `DROP INDEX` | `DROP INDEX IF EXISTS esq_credito.idx_tb_credito_legacy;` |
+| `CREATE SEQUENCE` | `CREATE SEQUENCE IF NOT EXISTS esq_credito.seq_tb_nueva;` |
+| `DROP SEQUENCE` | `DROP SEQUENCE IF EXISTS esq_credito.seq_tb_legacy;` |
+| `CREATE TABLE ... AS SELECT` | Reconstrucción desde backup |
+| Constraint `ADD/DROP` | `ALTER TABLE tb_x ADD CONSTRAINT pk_tb_x PRIMARY KEY (id_x);` |
+
+### `02-ddl-funciones/` — Funciones y Stored Procedures
+
+| Patrón | Ejemplos |
+|---|---|
+| `CREATE [OR REPLACE] FUNCTION` | `CREATE OR REPLACE FUNCTION esq_credito.fn_calcular_cuota(...)` |
+| `CREATE [OR REPLACE] PROCEDURE` | `CREATE OR REPLACE PROCEDURE esq_credito.sp_genera_credito(...)` |
+| `DROP FUNCTION` | `DROP FUNCTION IF EXISTS esq_credito.fn_legacy(integer, numeric);` |
+| `DROP PROCEDURE` | `DROP PROCEDURE IF EXISTS esq_credito.sp_legacy(integer);` |
+| `CREATE [OR REPLACE] VIEW` | Vistas con lógica de negocio compleja |
+| `DROP VIEW` | `DROP VIEW IF EXISTS esq_credito.vw_resumen_credito;` |
+
+> **Nota**: La firma completa (incluyendo tipos de parámetros) es necesaria en `DROP FUNCTION`/`DROP PROCEDURE` para evitar ambigüedad en PostgreSQL.
+
+### `03-migracion/` — Transformación de datos existentes
+
+| Patrón | Ejemplos |
+|---|---|
+| `UPDATE` sobre tabla existente | `UPDATE esq_credito.tb_credito SET estado = 1 WHERE estado IS NULL;` |
+| `INSERT ... SELECT ...` | Copiar/transformar datos entre tablas |
+| `DELETE` sobre datos existentes | `DELETE FROM tb_x WHERE fecha_registro < '2020-01-01';` |
+| Relleno de nueva columna | `UPDATE tb_x SET nueva_col = fn_calcula(otra_col);` |
+| Normalización de datos | Separar una columna en múltiples, fusionar tablas |
+| Migración de tipo de dato | Copiar valores transformados antes de cambiar tipo |
+
+> **Importante**: Cualquier script de migración debe ir precedido de un `000-backup-<tabla>.sql` que respalde las filas afectadas a `esq_audit`.
+
+### `04-inserts/` — Datos nuevos (seeds / catálogos)
+
+| Patrón | Ejemplos |
+|---|---|
+| `INSERT INTO ... VALUES (...)` | Registros de `tb_maestra_detalle`, roles, perfiles |
+| Seeds de configuración | Parámetros iniciales, valores de lookup |
+| Datos de referencia | Países, monedas, estados de proceso |
+| `INSERT ... ON CONFLICT DO NOTHING` | Idempotent inserts de catálogos |
+| `INSERT ... ON CONFLICT DO UPDATE` | Upserts de configuración |
+
+---
+
+## Edge cases y scripts mixtos
+
+### Script con DDL + DML (mezcla)
+
+Si un script crea una tabla Y la puebla inmediatamente (patrón común en seeds):
+
+**Opción A (recomendada)**: Dividir en dos scripts — `01-ddl-tablas/001-crea-tb-x.sql` + `04-inserts/001-inserta-tb-x.sql`.
+
+**Opción B**: Si la división no tiene sentido semántico (ej: tabla temporal de trabajo que se llena y elimina en la misma operación), clasificar según la operación **dominante**. Documentar en el `README.md` del bundle.
+
+### Scripts de respaldo previo (`000-backup-*.sql`)
+
+Los scripts de respaldo pertenecen a la misma categoría que su script de migración:
+- `03-migracion/000-backup-tb-credito.sql` precede a `03-migracion/001-migra-estado.sql`
+- Numeración especial `000` para indicar que va primero dentro de la categoría
+
+### Funciones de apoyo temporal
+
+Si un script `03-migracion` usa una función **solo dentro de ese script** (creada y eliminada en el mismo archivo), **no** moverla a `02-ddl-funciones/`. Usar un bloque `DO $$ ... $$` o una CTE en su lugar, siguiendo la regla "sin funciones utilitarias efímeras".
+
+### Scripts de versionado de funciones (`_v2`, `_v3`)
+
+Al actualizar una función a una nueva versión:
+- `02-ddl-funciones/001-actualiza-fn-x-v2.sql` → `CREATE OR REPLACE FUNCTION fn_x(...)`
+- El rollback contiene la versión anterior (`v1`) para restaurar en caso necesario
+- **No eliminar** la versión anterior hasta confirmar que `v2` funciona en producción
+
+### Views
+
+Clasificar en `02-ddl-funciones/` (mismo directorio que funciones). Las views son DDL de objetos de BD, no migración de datos.
+
+---
+
+## Resolución de dependencias entre categorías
+
+Al renumerar, verificar:
+
+1. `03-migracion` no puede referenciar una columna creada en `01-ddl-tablas` si ese script aún no fue ejecutado
+2. `04-inserts` no puede insertar en una tabla que existe solo en `01-ddl-tablas` del mismo bundle (al ejecutar prod, ir en orden)
+3. `02-ddl-funciones` puede depender de tablas de `01-ddl-tablas` — verificar que la función no se crea antes que su tabla
+
+Si se detecta una dependencia circular o un orden imposible, dividir el bundle en sub-bundles y documentarlo en `README.md`.
+
+---
+
+## Nomenclatura de archivos
+
+Formato: `NNN-verbo-sustantivo-objetivo.sql`
+
+| Elemento | Regla | Ejemplos |
+|---|---|---|
+| `NNN` | 3 dígitos, cero-padded dentro de la categoría | `001`, `002`, `010` |
+| `verbo` | acción que realiza el script | `crea`, `elimina`, `modifica`, `migra`, `inserta`, `actualiza`, `agrega` |
+| `sustantivo` | objeto principal afectado | `tb-credito`, `fn-calcular-cuota`, `sp-genera-credito` |
+| `objetivo` | detalle adicional si es necesario | `columna-estado`, `v2`, `sesion-inicial` |
+
+Ejemplos válidos:
+- `001-crea-tb-solicitud.sql`
+- `002-agrega-columna-flag-activo-tb-credito.sql`
+- `001-crea-fn-calcular-cuota-v2.sql`
+- `001-migra-estado-credito.sql`
+- `000-backup-tb-credito.sql`
+- `001-inserta-maestras-estado-solicitud.sql`

package/skills/agent-workflow/standards/sql-script-organizer/references/consolidation-cross-session.md

@@ -0,0 +1,125 @@
+# Consolidación cross-session (release) y modo por tema
+
+Detalles del comportamiento de `sql-script-organizer` cuando es invocado por `release` (cross-session) o por `release-scripts` (por tema). El SKILL.md tiene el resumen; este archivo tiene el procedimiento completo.
+
+## Modo consolidación cross-session (delegado por `release`)
+
+Produce un bundle único que abarca múltiples sesiones en `docs/release/NNN-release-YYYY-MM-DD/scripts/`.
+
+### Entrada
+
+Lista de bundles fuente en orden cronológico de sesión:
+- Sesiones cerradas: `docs/scripts/NNN-sessionXXX-*/` (ya graduados).
+- Sesiones abiertas: `.workflow/sessions/sessionXXX-*/scripts/bundle/` o `scripts/` flat (organizar antes).
+
+### Proceso
+
+1. **Validar organización** de cada bundle fuente. Si flat, aplicar el proceso estándar de las 4 categorías antes.
+2. **Crear estructura destino** con `01-ddl-tablas/`, `02-ddl-funciones/`, `03-migracion/`, `04-inserts/`, `rollback/`.
+3. **Copiar scripts preservando orden**:
+   - Sesiones cronológicas (session001 → session002 → …).
+   - Dentro de cada sesión, orden 01→02→03→04.
+   - Renumerar `NNN` continuo dentro de la categoría.
+   - Header de origen:
+     ```sql
+     -- Origen: sessionXXX-nombre · docs/scripts/NNN-sessionXXX-nombre/03-migracion/001-xyz.sql
+     -- Consolidado en release NNN (YYYY-MM-DD)
+     ```
+   - El `.rollback.sql` viaja con su forward.
+4. **No fusionar** scripts distintos en un único archivo.
+5. **Resolver conflictos cross-sesión**: documentar en `scripts/README.md` si una migración depende de algo reemplazado.
+6. **Generar `scripts/README.md`** con:
+   - Secuencia de ejecución lineal.
+   - Tabla "script en release | sesión origen | script original".
+   - Listado de irreversibles.
+7. **Delegar a `sql-rollback-generator`** para el rollback global.
+
+### Qué NO hacer
+
+- Modificar scripts originales en `docs/scripts/NNN-sessionXXX-*/` — son memoria permanente.
+- Mezclar sentencias de scripts distintos.
+- Renombrar categorías — siempre 01→02→03→04.
+- Saltar sesiones sin registrarlo.
+
+### Layout del bundle consolidado
+
+```
+docs/release/NNN-release-YYYY-MM-DD/scripts/
+├── README.md                          (mapeo sesión → script + secuencia)
+├── 01-ddl-tablas/
+│   ├── 001-crea-tb-x.sql              (origen: session001)
+│   ├── 001-crea-tb-x.rollback.sql
+│   ├── 002-crea-tb-y.sql              (origen: session003)
+│   └── 002-crea-tb-y.rollback.sql
+├── 02-ddl-funciones/
+│   └── ...
+├── 03-migracion/
+│   ├── 000-backup-tb-x.sql            (origen: session001)
+│   ├── 001-migra-col-z.sql
+│   ├── 001-migra-col-z.rollback.sql
+│   └── ...
+├── 04-inserts/
+│   └── ...
+└── rollback/
+    └── 00-rollback-release.sql        (sql-rollback-generator)
+```
+
+### Confirmación
+
+Si el usuario no confirmó producir el bundle consolidado, NO crear la carpeta. Referenciar bundles graduados por sesión y listar ejecución lineal.
+
+## Modo por tema consolidado (delegado por `release-scripts`)
+
+Reutiliza la clasificación 01→04 pero la aplica **dentro de cada tema** y **consolida** todos los scripts de una misma `(tema, categoría)` en un único `.sql`.
+
+### Layout destino
+
+```
+docs/release/NNN-release-YYYY-MM-DD/scripts-por-tema/
+└── tema-<slug>/
+    ├── 01-ddl-tablas.sql              (consolidado, BEGIN/COMMIT único)
+    ├── 01-ddl-tablas.rollback.sql     (consolidado inverso)
+    ├── 02-ddl-funciones.sql
+    ├── 02-ddl-funciones.rollback.sql
+    ├── 03-migracion.sql
+    ├── 03-migracion.rollback.sql
+    ├── 04-inserts.sql
+    ├── 04-inserts.rollback.sql
+    └── rollback-tema-<slug>.sql       (revierte el tema completo)
+```
+
+### Qué cambia respecto al modo estándar
+
+- **Consolidación**: N scripts de `(tema, categoría)` se concatenan en un único archivo. Eliminar `BEGIN;`/`COMMIT;` de cada uno; añadir `BEGIN;` único al inicio y `COMMIT;` al final. Transacción atómica por categoría del tema.
+- **Trazabilidad**: separador `-- === [i/N] <nombre-original> ===` + ruta canónica.
+- **Sin subcarpetas por categoría**: el nombre de archivo ya indica la categoría.
+- **Categorías vacías** no se crean.
+- **Scripts fuente preservados opt** con `--keep-parts` → `parts/<categoria>/*.sql`.
+- **Orden cross-tema**: en `ORDER.md` (resuelto por `release-scripts`).
+
+### Qué NO cambia
+
+- Las 4 categorías y sus patrones.
+- Las reglas de estilo SQL.
+- El bundle plano sigue generándose igual; el modo por-tema es aditivo.
+
+### Formato del archivo consolidado
+
+```sql
+-- Tema: <slug>
+-- Categoría: 01-ddl-tablas
+-- Release: NNN (YYYY-MM-DD)
+-- Consolidado: <nombre1>.sql, <nombre2>.sql, …
+
+BEGIN;
+
+-- [1/N] <nombre>.sql (origen: sessionXXX)
+<contenido sin BEGIN/COMMIT>
+
+-- [2/N] <nombre>.sql (origen: sessionXXX)
+<contenido>
+
+COMMIT;
+```
+
+Ver `release-scripts/SKILL.md` y `release-scripts/references/theme-detection.md` para asignación script→tema.