@tacuchi/agent-workflow-cli 11.0.1 → 12.0.0

package/skills/agent-workflow/standards/sql-rollback-generator/references/release-rollback.md

@@ -1,133 +0,0 @@
-# Rollback global de release y por tema (LEGACY — deprecation Fase 1)
-
-> **Estado**: legacy. Aplica solo a `release` / `release-scripts` legacy (deprecation Fase 1). El reemplazo canónico es `/agent-workflow:export-scripts` v4.0.0+, que produce un único `00-ROLLBACK.sql` cross-session al root del bundle (algoritmo en `SKILL.md` v2.0.0).
-
-Algoritmos detallados para rollbacks consolidados en modo release legacy. El SKILL.md tiene el resumen; este archivo tiene el procedimiento completo paso a paso.
-
-## Rollback global de release (cross-session)
-
-`docs/release/NNN-release-YYYY-MM-DD/scripts/rollback/00-rollback-release.sql` revierte el release completo.
-
-### Principio
-
-Revertir en **orden inverso absoluto**:
-- Sesiones: última → primera (session_N → … → session_1).
-- Dentro de cada sesión: 04 → 03 → 02 → 01 (contrario al de ejecución).
-
-### Proceso
-
-1. Recolectar todos los `.rollback.sql` del bundle consolidado.
-2. Ordenar inversamente: primero todos los rollbacks de la sesión más reciente (04→01), luego la anterior, etc.
-3. Encadenar en un único archivo:
-
-```sql
--- Rollback global del Release NNN (YYYY-MM-DD)
--- Cubre N sesiones desde sessionXXX hasta sessionYYY
-BEGIN;
-
--- sessionYYY-nombre (última)
--- 04-inserts
-[contenido en orden inverso]
--- 03-migracion
-[contenido en orden inverso]
--- 02-ddl-funciones
-[contenido en orden inverso]
--- 01-ddl-tablas
-[contenido en orden inverso]
-
--- sessionXXX-nombre-previo
-[misma estructura]
-
-COMMIT;
-```
-
-4. Preservar marcas `-- WARNING: IRREVERSIBLE` con contexto (sesión origen).
-5. Listar irreversibles al inicio antes del `BEGIN;`:
-
-```sql
--- ADVERTENCIA: Este release contiene [N] operaciones irreversibles:
--- - sessionXXX / 03-migracion/001-*.sql — DROP COLUMN (mitigación: esq_audit.tb_bkp_*_sessionXXX)
--- - sessionYYY / 01-ddl-tablas/002-*.sql — DROP TABLE CASCADE (mitigación: sin respaldo)
--- Revisar docs/release/NNN-informe-release.md sección 4.2 antes de ejecutar.
-```
-
-### Qué NO hacer
-
-- Fusionar rollbacks de distintas sesiones sobre la misma tabla — dejar cada bloque independiente.
-- Cambiar el orden inverso — puede dejar referencias colgando.
-- Ejecutar el rollback desde el plugin. Siempre manual por el usuario.
-
-### Verificación mínima
-
-- Orden inverso absoluto respetado (sesiones descendente, categorías 04→01).
-- Operaciones irreversibles listadas al inicio.
-- Archivo abre con `BEGIN;` y cierra con `COMMIT;`.
-- Cada bloque de sesión delimitado con `-- === sessionXXX ===`.
-- Headers de respaldo preservados donde aplica.
-
-## Rollback por tema (delegado por release-scripts)
-
-Tres niveles:
-
-1. **Consolidado por categoría**: `tema-<slug>/<categoria>.rollback.sql` concatena rollbacks de scripts fuente en orden inverso, envuelto en `BEGIN; … COMMIT;`.
-2. **Por-tema**: `tema-<slug>/rollback-tema-<slug>.sql` encadena los 4 consolidados (04→03→02→01).
-3. **Global del release**: `rollback/00-rollback-release.sql` encadena rollbacks por-tema en orden inverso a `ORDER.md`.
-
-### Generación del consolidado por categoría
-
-1. Recolectar `.rollback.sql` correspondientes al consolidado forward.
-2. Ordenar inversamente: último script primero.
-3. Eliminar `BEGIN;`/`COMMIT;` de cada rollback individual.
-4. Concatenar con separadores `[i/N]`.
-5. Envolver en un único `BEGIN; … COMMIT;`.
-
-### Generación del rollback por-tema
-
-```sql
--- Rollback del tema <slug> — Release NNN (revierte 04→01)
-BEGIN;
-
--- 04-inserts
-[contenido sin BEGIN/COMMIT]
-
--- 03-migracion
-[contenido sin BEGIN/COMMIT]
-
--- 02-ddl-funciones
-[contenido sin BEGIN/COMMIT]
-
--- 01-ddl-tablas
-[contenido sin BEGIN/COMMIT]
-
-COMMIT;
-```
-
-Preservar marcas `-- WARNING: IRREVERSIBLE` y listarlas al inicio.
-
-### Generación del global
-
-1. Tomar `rollback-tema-<slug>.sql` de todos los temas.
-2. Ordenar inversamente al de `ORDER.md`.
-3. Encadenar inline (no `\i` includes) en un único `BEGIN; … COMMIT;`.
-4. Listar irreversibles al inicio agrupadas por tema origen.
-
-### Multi-tema en rollback
-
-Scripts multi-tema se incluyen sólo en el consolidado del tema canónico. Su rollback aparece sólo allí; los demás temas no lo duplican. El global lo incluye una vez.
-
-### Qué NO hacer
-
-- Duplicar contenido entre consolidados.
-- Cambiar el orden de categorías dentro del rollback por-tema (siempre 04→03→02→01).
-- Generar consolidados de rollback para categorías sin forwards.
-- Dejar `BEGIN;`/`COMMIT;` de scripts individuales dentro de los consolidados.
-
-### Verificación mínima
-
-- Cada consolidado forward tiene su rollback consolidado.
-- Bloques en orden inverso al forward.
-- Cada tema con scripts tiene su `rollback-tema-<slug>.sql`.
-- El global encadena en orden inverso a `ORDER.md`.
-- Irreversibles listados al inicio del global, agrupados por tema origen.
-- Ningún rollback multi-tema duplicado.
-- Cada archivo abre con `BEGIN;` y cierra con `COMMIT;` (uno solo por archivo).

package/skills/agent-workflow/standards/sql-rollback-generator/references/rollback-patterns.md

@@ -1,257 +0,0 @@
-# Patrones de Rollback SQL
-
-Recetas por tipo de operación. Motor primario: **PostgreSQL**. Se incluyen equivalencias para otros motores donde difieren.
-
----
-
-## DDL de Tablas
-
-### CREATE TABLE → DROP TABLE
-
-```sql
--- Forward
-BEGIN;
-CREATE TABLE IF NOT EXISTS esq_credito.tb_nueva (
-    id_nueva    integer         NOT NULL DEFAULT nextval('esq_credito.seq_tb_nueva'),
-    nombre      varchar(100)    NOT NULL,
-    estado      integer         NOT NULL DEFAULT 1,
-    CONSTRAINT pk_tb_nueva PRIMARY KEY (id_nueva)
-);
-COMMIT;
-
--- Rollback
-BEGIN;
-DROP TABLE IF EXISTS esq_credito.tb_nueva;
-DROP SEQUENCE IF EXISTS esq_credito.seq_tb_nueva;  -- si la secuencia fue creada junto a la tabla
-COMMIT;
-```
-
-### ALTER TABLE ADD COLUMN → DROP COLUMN
-
-```sql
--- Forward
-BEGIN;
-ALTER TABLE esq_credito.tb_credito
-    ADD COLUMN IF NOT EXISTS flag_reestructurado integer NOT NULL DEFAULT 0;
-COMMIT;
-
--- Rollback
-BEGIN;
-ALTER TABLE esq_credito.tb_credito
-    DROP COLUMN IF EXISTS flag_reestructurado;
-COMMIT;
-```
-
-### DROP TABLE (con respaldo previo)
-
-```sql
--- 000-backup-tb-x.sql (siempre antes del DROP)
-BEGIN;
-CREATE TABLE IF NOT EXISTS esq_audit.tb_bkp_credito_sessionXXX
-    AS SELECT * FROM esq_credito.tb_credito_legacy;
-COMMIT;
-
--- Forward
-BEGIN;
-DROP TABLE IF EXISTS esq_credito.tb_credito_legacy;
-COMMIT;
-
--- Rollback
-BEGIN;
-CREATE TABLE IF NOT EXISTS esq_credito.tb_credito_legacy
-    AS SELECT * FROM esq_audit.tb_bkp_credito_sessionXXX;
--- Restaurar constraints si aplica:
-ALTER TABLE esq_credito.tb_credito_legacy
-    ADD CONSTRAINT pk_tb_credito_legacy PRIMARY KEY (id_credito_legacy);
-COMMIT;
-```
-
-### CREATE INDEX → DROP INDEX
-
-```sql
--- Forward
-CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_tb_credito_cliente
-    ON esq_credito.tb_credito(id_cliente);
-
--- Rollback
-DROP INDEX CONCURRENTLY IF EXISTS esq_credito.idx_tb_credito_cliente;
-```
-
-> `CONCURRENTLY` no puede ir dentro de `BEGIN/COMMIT` en PostgreSQL — ejecutar fuera de transacción o sin `CONCURRENTLY` dentro de transacción.
-
----
-
-## DDL de Funciones y SP
-
-### CREATE OR REPLACE FUNCTION → DROP FUNCTION
-
-```sql
--- Forward
-BEGIN;
-CREATE OR REPLACE FUNCTION esq_credito.fn_calcular_cuota_v2(
-    p_monto     numeric,
-    p_tasa      numeric,
-    p_plazo     integer
-) RETURNS numeric
-LANGUAGE plpgsql AS $$
-BEGIN
-    RETURN p_monto * (p_tasa / 12) / (1 - POWER(1 + p_tasa / 12, -p_plazo));
-END;
-$$;
-COMMIT;
-
--- Rollback: eliminar nueva versión y restaurar la anterior (si existe)
-BEGIN;
-DROP FUNCTION IF EXISTS esq_credito.fn_calcular_cuota_v2(numeric, numeric, integer);
--- Si existía v1, recrear aquí:
--- CREATE OR REPLACE FUNCTION esq_credito.fn_calcular_cuota(...) ...
-COMMIT;
-```
-
-> **Siempre incluir la firma completa en `DROP FUNCTION`** (tipos de parámetros). PostgreSQL puede tener múltiples sobrecargas del mismo nombre.
-
-### DROP FUNCTION irreversible
-
-```sql
--- WARNING: IRREVERSIBLE — no hay versión anterior registrada
--- Rollback best-effort: cuerpo de la función para restauración manual
-BEGIN;
-DROP FUNCTION IF EXISTS esq_credito.fn_legacy(integer);
-COMMIT;
-
-/*
-  RESTAURACIÓN MANUAL si se necesita revertir:
-  CREATE OR REPLACE FUNCTION esq_credito.fn_legacy(p_id integer)
-  RETURNS void LANGUAGE plpgsql AS $$
-  BEGIN
-      -- [cuerpo de la función aquí]
-  END;
-  $$;
-*/
-```
-
----
-
-## Migración de Datos
-
-### UPDATE masivo → restaurar desde backup
-
-```sql
--- 000-backup-tb-credito.sql
-BEGIN;
-CREATE TABLE IF NOT EXISTS esq_audit.tb_bkp_credito_sessionXXX AS
-SELECT id_credito, estado, estado_proceso
-FROM esq_credito.tb_credito
-WHERE estado = 0 AND fecha_registro < '2024-01-01';
-COMMIT;
-
--- Forward: migración
-BEGIN;
-UPDATE esq_credito.tb_credito
-SET estado = 2
-WHERE estado = 0 AND fecha_registro < '2024-01-01';
-COMMIT;
-
--- Rollback: restaurar desde backup
-BEGIN;
-UPDATE esq_credito.tb_credito t
-SET estado = bkp.estado
-FROM esq_audit.tb_bkp_credito_sessionXXX bkp
-WHERE t.id_credito = bkp.id_credito;
-COMMIT;
-```
-
-### INSERT ... SELECT → DELETE por rango
-
-```sql
--- Forward: poblar tabla destino desde origen
-BEGIN;
-INSERT INTO esq_credito.tb_credito_nuevo (id_credito, monto, estado)
-SELECT id_credito, monto_prestamo, 1
-FROM esq_credito.tb_credito_legacy
-WHERE flag_migrado = 0;
-COMMIT;
-
--- Rollback: eliminar solo los registros insertados en esta sesión
-BEGIN;
-DELETE FROM esq_credito.tb_credito_nuevo
-WHERE id_credito IN (
-    SELECT id_credito FROM esq_credito.tb_credito_legacy WHERE flag_migrado = 0
-);
-COMMIT;
-```
-
----
-
-## Inserts de datos nuevos
-
-### INSERT simple → DELETE por clave natural
-
-```sql
--- Forward
-BEGIN;
-INSERT INTO esq_sistema.tb_maestra_detalle
-    (id_maestra, codprog, descripcion, valor, estado, usuario_registro, fecha_registro)
-VALUES
-    (1, 'EST_SOLICITUD', 'Pendiente',  1, 1, 'session_deploy', NOW()),
-    (1, 'EST_SOLICITUD', 'Aprobada',   2, 1, 'session_deploy', NOW()),
-    (1, 'EST_SOLICITUD', 'Rechazada',  3, 1, 'session_deploy', NOW())
-ON CONFLICT DO NOTHING;
-COMMIT;
-
--- Rollback
-BEGIN;
-DELETE FROM esq_sistema.tb_maestra_detalle
-WHERE codprog = 'EST_SOLICITUD'
-  AND valor IN (1, 2, 3)
-  AND usuario_registro = 'session_deploy';
-COMMIT;
-```
-
----
-
-## Bloque rollback de una sesión dentro de `00-ROLLBACK.sql`
-
-```sql
--- ----------------------------------------------------------------------------
--- ROLLBACK de sessionXXX-[nombre] — revierte los cambios en orden inverso.
--- Forma parte del 00-ROLLBACK.sql cross-session del bundle.
--- ----------------------------------------------------------------------------
-BEGIN;
-
--- Paso 4 invertido: deshacer inserts
-DELETE FROM esq_sistema.tb_maestra_detalle
-WHERE codprog = 'EST_SOLICITUD' AND usuario_registro = 'session_deploy';
-
--- Paso 3 invertido: deshacer migraciones
-UPDATE esq_credito.tb_credito t
-SET estado = bkp.estado
-FROM esq_audit.tb_bkp_credito_sessionXXX bkp
-WHERE t.id_credito = bkp.id_credito;
-
--- Paso 2 invertido: eliminar funciones nuevas
-DROP FUNCTION IF EXISTS esq_credito.fn_calcular_cuota_v2(numeric, numeric, integer);
-
--- Paso 1 invertido: eliminar tablas nuevas
-DROP TABLE IF EXISTS esq_credito.tb_nueva;
-DROP SEQUENCE IF EXISTS esq_credito.seq_tb_nueva;
-
-COMMIT;
-```
-
----
-
-## Equivalencias entre motores
-
-| Concepto | PostgreSQL | Oracle | SQL Server |
-|---|---|---|---|
-| Idempotencia CREATE TABLE | `CREATE TABLE IF NOT EXISTS` | `BEGIN EXECUTE IMMEDIATE ... EXCEPTION WHEN OTHERS THEN NULL; END;` | `IF NOT EXISTS (SELECT...) CREATE TABLE` |
-| Idempotencia DROP | `DROP TABLE IF EXISTS` | No nativo — usar bloque PL/SQL | `DROP TABLE IF EXISTS` (2016+) |
-| Create o reemplazar función | `CREATE OR REPLACE FUNCTION` | `CREATE OR REPLACE FUNCTION` | `CREATE OR ALTER PROCEDURE` |
-| Insertar sin duplicar | `ON CONFLICT DO NOTHING` | `INSERT INTO ... WHERE NOT EXISTS (SELECT 1 ...)` | `IF NOT EXISTS (SELECT 1 ...) INSERT` |
-| Esquema explícito | `esq_credito.tb_x` | `schema.tb_x` | `[schema].[tb_x]` |
-| Secuencias | `CREATE SEQUENCE` / `nextval(...)` | `CREATE SEQUENCE` / `.NEXTVAL` | `IDENTITY` o `SEQUENCE` (2012+) |
-| Transacción | `BEGIN; ... COMMIT;` | `-- implícita; usar COMMIT;` | `BEGIN TRANSACTION; ... COMMIT;` |
-| Creación condicional índice | `CREATE INDEX IF NOT EXISTS` | No nativo | `IF NOT EXISTS (SELECT...) CREATE INDEX` |
-
-> Si el motor de destino no es PostgreSQL, indicarlo en el header del script y ajustar la sintaxis según la tabla anterior.

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

@@ -1,243 +0,0 @@
----
-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 v5.0.0)
-
-`/agent-workflow:export-scripts` v5.0.0+ produce el bundle al ejecutarse, no este skill. Layout plano con **numeración continua** tras `00-ROLLBACK.sql`:
-
-```
-<docs>/scripts/NNN-export-scripts-YYYY-MM-DD/
-├── 00-ROLLBACK.sql                            (único rollback cross-session — sql-rollback-generator v3.0.0)
-├── 01-<CATEGORIA>.sql                         (primera categoría con contenido)
-├── 02-<CATEGORIA>.sql                         (segunda categoría con contenido, si aplica)
-├── ...                                        (numeración continua, sin gaps por categoría vacía)
-└── README.md                                  (índice + cómo aplicar + cómo revertir)
-```
-
-Orden canónico de las categorías (para asignar número): `DDL-TABLES` → `DDL-FUNCTIONS` → `DML` → `INSERTS`. Las vacías no ocupan número. Si sólo hay DML, el archivo se llama `01-DML.sql`.
-
-Sentencias individuales del `SCRIPTS.sql` per-sesión se consolidan **cross-session** al archivo de su categoría — no se crea sub-carpeta por sesión.
-
-Layout **v3.x** (`por-sesion/<sessionXXX>/01-04/*.sql + .rollback.sql` companions + per-sesión `rollback/`) ya **no se genera** desde v4.0.0. Layout **v4.0.0** (números fijos 01-04 con gaps) reemplazado por numeración continua en v5.0.0. Bundles ya escritos con layouts previos quedan como histórico.
-
-Layout **legacy** pre-SCRIPTS.sql (`scripts/01-04/*.sql + .rollback.sql` directo en sesión) tampoco 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`** v3.0.0+ — **on-export**: lee los forwards ya consolidados por `export-scripts` (no `SCRIPTS.sql` original) y genera `00-ROLLBACK.sql` único.
-- **`export-scripts`** v5.0.0+ — consume `SCRIPTS.sql` per sesión + `docs/scripts/*.sql` standalone, clasifica por categoría y asigna numeración continua tras `00-ROLLBACK.sql`. 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).