@tacuchi/agent-workflow-cli 6.1.0 → 7.0.0

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

@@ -0,0 +1,161 @@
+# Checklist de Operaciones Irreversibles
+
+Operaciones que no pueden revertirse automáticamente. Requieren protocolo especial antes de ejecutar.
+
+---
+
+## Protocolo ante una operación irreversible
+
+Antes de ejecutar cualquier operación de esta lista:
+
+1. **Agregar `-- WARNING: IRREVERSIBLE`** en el header del forward script
+2. **Crear script de respaldo** si hay datos en riesgo (ver plantillas en `rollback-patterns.md`)
+3. **Registrar en `DECISIONS.md`** de la sesión:
+   - Qué se va a ejecutar
+   - Por qué no es reversible
+   - Qué backup existe (o por qué no aplica)
+   - Confirmación explícita del usuario
+4. **Generar rollback best-effort** con nota `-- RESTAURACIÓN MANUAL REQUERIDA` si el rollback automático no es posible
+5. **Checkpoint**: el usuario debe confirmar explícitamente antes de continuar
+
+---
+
+## Lista de operaciones irreversibles
+
+### TRUNCATE TABLE
+
+```sql
+-- WARNING: IRREVERSIBLE
+-- Elimina TODOS los datos de la tabla sin posibilidad de rollback transaccional en algunos motores.
+-- En PostgreSQL se puede envolver en BEGIN/COMMIT, pero el efecto es inmediato si se confirma.
+-- Respaldo obligatorio en esq_audit antes de ejecutar.
+```
+
+**Mitigación**: `CREATE TABLE esq_audit.tb_bkp_x_sessionXXX AS SELECT * FROM esq_.tb_x;` antes.
+
+---
+
+### DROP COLUMN sin respaldo previo
+
+```sql
+-- WARNING: IRREVERSIBLE
+-- La columna y sus datos se pierden permanentemente.
+-- Respaldo: ALTER TABLE tb_x ADD COLUMN col_bkp ... + UPDATE SET col_bkp = col_original;
+-- o bien: CREATE TABLE esq_audit.tb_bkp_x_col_sessionXXX AS SELECT id, col FROM tb_x;
+```
+
+**Mitigación**: copiar los valores a una columna temporal o tabla de backup antes del DROP.
+
+---
+
+### DROP TABLE sin respaldo previo
+
+```sql
+-- WARNING: IRREVERSIBLE
+-- La tabla y todos sus datos, índices, constraints y sequences asociados se pierden.
+-- Respaldo obligatorio: CREATE TABLE esq_audit.tb_bkp_x_sessionXXX AS SELECT * FROM esq_.tb_x;
+```
+
+---
+
+### ALTER COLUMN TYPE con pérdida de precisión
+
+```sql
+-- WARNING: IRREVERSIBLE
+-- Cambiar de varchar(500) a varchar(50) trunca datos. Cambiar de numeric(18,4) a integer pierde decimales.
+-- Verificar que no hay datos que excedan el nuevo tamaño/precisión ANTES de ejecutar.
+```
+
+**Mitigación**:
+```sql
+-- Verificar antes:
+SELECT COUNT(*) FROM esq_.tb_x WHERE length(col_x) > 50;
+SELECT COUNT(*) FROM esq_.tb_x WHERE col_x != FLOOR(col_x);
+```
+
+---
+
+### DROP ... CASCADE
+
+```sql
+-- WARNING: IRREVERSIBLE
+-- Elimina el objeto Y todos los objetos que dependen de él (views, funciones, constraints).
+-- Listar dependencias antes: SELECT * FROM information_schema.constraint_column_usage WHERE table_name = 'tb_x';
+```
+
+**Mitigación**: antes de ejecutar, listar todas las dependencias y generar los scripts para recrearlas.
+
+---
+
+### DELETE sin WHERE (o con WHERE muy amplio)
+
+```sql
+-- WARNING: IRREVERSIBLE
+-- Un DELETE sin cláusula WHERE o con condición demasiado amplia puede vaciar una tabla.
+-- Respaldo obligatorio: CREATE TABLE esq_audit.tb_bkp_x_sessionXXX AS SELECT * FROM esq_.tb_x WHERE <condicion>;
+```
+
+**Verificación previa recomendada**:
+```sql
+-- Ejecutar primero como SELECT para ver qué filas afecta:
+SELECT COUNT(*) FROM esq_.tb_x WHERE <condicion_del_delete>;
+```
+
+---
+
+### UPDATE sin WHERE sobre tabla grande
+
+```sql
+-- WARNING: ALTA SUPERFICIE DE IMPACTO
+-- Un UPDATE sin WHERE o con condición muy amplia modifica todas las filas.
+-- Si es intencional, documentarlo explícitamente en DECISIONS.md.
+-- Respaldo obligatorio antes de ejecutar.
+```
+
+---
+
+### Eliminar función sin versión anterior conocida
+
+```sql
+-- WARNING: IRREVERSIBLE
+-- Si no hay registro de la versión anterior de la función (no está en el repo ni en la sesión),
+-- no es posible generar un rollback automático.
+-- El rollback best-effort debe incluir el cuerpo actual en un comentario para restauración manual.
+```
+
+---
+
+### Cambiar tipo de columna con conversión destructiva
+
+Por ejemplo: `varchar` → `integer` donde algunos valores no son números; `timestamp` → `date` perdiendo la hora.
+
+**Mitigación**:
+```sql
+-- Verificar antes:
+SELECT col_x FROM esq_.tb_x WHERE col_x !~ '^\d+$';  -- filas que no son números
+```
+
+---
+
+## Formato del header para scripts irreversibles
+
+```sql
+-- Archivo: 001-elimina-col-legacy-tb-credito.sql
+-- Sesión: sessionXXX-nombre-kebab (YYYY-MM-DD)
+-- WARNING: IRREVERSIBLE — DROP COLUMN sin restauración automática posible
+-- Respaldo: esq_audit.tb_bkp_credito_col_legacy_sessionXXX (creado en 000-backup.sql)
+-- Decisión: DECISIONS.md DEC-XXX — aprobado por [usuario]
+BEGIN;
+-- cuerpo del script
+COMMIT;
+```
+
+---
+
+## Verificaciones antes de ejecutar en producción
+
+- [ ] El script de respaldo fue ejecutado y verificado (`SELECT COUNT(*) FROM esq_audit.tb_bkp_...`)
+- [ ] La decisión está registrada en `DECISIONS.md`
+- [ ] El usuario confirmó explícitamente la ejecución
+- [ ] Se tiene el rollback best-effort documentado (aunque sea manual)
+- [ ] Se notificó al equipo si el cambio afecta a otros servicios

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

@@ -0,0 +1,131 @@
+# Rollback global de release y por tema
+
+Algoritmos detallados para rollbacks consolidados en modo release. 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

@@ -0,0 +1,255 @@
+# 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;
+```
+
+---
+
+## Bundle global (`00-rollback-global.sql`)
+
+```sql
+-- ROLLBACK GLOBAL — sessionXXX-[nombre]
+-- Revierte TODOS los cambios en orden inverso. Ejecutar sólo para deshacer la sesión completa.
+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.