@tacuchi/agent-workflow-cli 6.1.0 → 7.0.0

package/skills/agent-workflow/standards/frontend-design/references/navigation-patterns.md

@@ -0,0 +1,224 @@
+# Patrones de navegación
+
+Principios de diseño para navegación en aplicaciones admin: sidebar, toolbar, breadcrumbs, tabs, routing, back navigation. Agnóstico a framework.
+
+Para el código del stack (routing, guards, lazy loading, store sincronizado con `NavigationEnd`), ver `coding-standards/references/<stack>.md`.
+
+---
+
+## 1. Layout admin de 2 zonas
+
+Las aplicaciones admin siguen un layout persistente con 2 zonas fijas alrededor del contenido:
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  Logo  [≡]     │   Breadcrumbs  |  Sucursal  Usuario  ⎋ │  ← toolbar (top)
+├─────────────┬──┴──────────────────────────────────────────┤
+│             │                                              │
+│  Sidebar    │  Contenido de la vista                       │
+│  (menu)     │  (title + action + filters + table/form)     │
+│             │                                              │
+│             │                                              │
+└─────────────┴──────────────────────────────────────────────┘
+```
+
+**Reglas:**
+
+- Toolbar fija en el top; sidebar fija a la izquierda.
+- El contenido de la vista se renderiza en el área central (`<router-outlet>`).
+- Sidebar colapsable: en desktop ocupa ~240 px expandida / ~60 px colapsada (solo íconos).
+- En mobile: sidebar se convierte en drawer overlay (`position: fixed` + backdrop).
+
+---
+
+## 2. Sidebar
+
+**Comportamiento:**
+
+- **Colapsable** con toggle desde la toolbar. Estado persistente (store + opcional localStorage) para que sobreviva a navegación entre páginas.
+- **Ítems dinámicos** leídos de un catálogo central (no hardcoded por app). El catálogo expone qué ve cada usuario según su rol.
+- **Ítem activo destacado** con clase `.active` + color de fondo o borde lateral. Sincronizado con la ruta actual vía evento del router (`NavigationEnd` en Angular).
+
+**Estructura de cada ítem:**
+
+```html
+<a class="sidebar-item" [class.active]="isActive" [title]="!sidebarOpen ? label : null">
+  <span class="sidebar-icon"><i class="fa fa-users"></i></span>
+  <span class="sidebar-label" *ngIf="sidebarOpen">{{ label }}</span>
+</a>
+```
+
+**Reglas:**
+
+- Ícono a la izquierda, label a la derecha. Label se oculta en colapsado; tooltip (`title`) lo sustituye.
+- Máximo 1 nivel de anidación visible; si el menú crece, agrupar por secciones con separador.
+- Ítems ordenados por frecuencia de uso del rol dominante (no alfabéticamente).
+- Pie opcional con "Volver al home" o enlace al cambio de app.
+
+---
+
+## 3. Toolbar (top bar)
+
+3 zonas horizontales:
+
+| Zona | Contenido |
+|------|-----------|
+| Izquierda | Logo + botón toggle del sidebar. |
+| Centro | Breadcrumbs (opcional — ver §5). |
+| Derecha (desktop) | Contexto (sucursal si es cambiable) + nombre usuario + avatar + logout. |
+| Derecha (mobile) | Solo avatar; al tap abre drawer con las opciones. |
+
+**Reglas:**
+
+- Logo siempre navegable al home (click → ruta raíz).
+- El **contexto** (sucursal activa, periodo contable, etc.) vive en la toolbar cuando es relevante al trabajo en curso y puede cambiarse globalmente.
+- **Avatar = iniciales** (primeras 2 letras del nombre, upper) si no hay foto. Badge redondo con color consistente por usuario.
+- Logout como enlace `⎋` o "Salir" — nunca oculto en un sub-menú innecesario.
+
+---
+
+## 4. Título de página + acción primaria (page header)
+
+Cada vista del área de contenido abre con un header consistente:
+
+```html
+<div class="mb-4">
+  <div class="d-flex justify-content-between align-items-center flex-wrap gap-3">
+    <div>
+      <h2 class="fw-bold mb-1">Título de la vista</h2>
+      <p class="text-muted mb-0">Descripción de una línea.</p>
+    </div>
+    <button class="btn btn-primary">Acción primaria</button>
+  </div>
+</div>
+```
+
+**Reglas:**
+
+- `h2 fw-bold` para el título, `p text-muted` para la descripción de una sola línea.
+- Acción primaria top-right; si no hay, el header queda sin botón (no forzar uno).
+- `flex-wrap gap-3` para que el botón baje en mobile sin solaparse.
+
+**[shared-candidato] `page-header`** — se repite en 6+ vistas; amerita extracción con slots `[title]`, `[subtitle]`, `[action]`. Ver también `list-patterns.md` §2 y `form-patterns.md` §2.
+
+---
+
+## 5. Breadcrumbs
+
+**Cuándo activarlos:**
+
+- Jerarquía de navegación es profunda (3+ niveles) y la ruta es relevante al usuario.
+- La URL no es suficientemente descriptiva (IDs en vez de nombres).
+
+**Cuándo omitirlos:**
+
+- App de 2 niveles (home → sección). El título de la vista ya indica dónde está el usuario.
+- Admin plano (todos los módulos al mismo nivel bajo `/admin`). El sidebar ya es la navegación principal.
+
+**Estructura cuando existen:**
+
+```html
+<nav class="breadcrumbs">
+  <a routerLink="/admin">Administración</a>
+  <span class="separator">›</span>
+  <a routerLink="/admin/usuario">Usuarios</a>
+  <span class="separator">›</span>
+  <span class="current">Editar</span>
+</nav>
+```
+
+**Reglas:**
+
+- Separador visual (`›`, `/`, `>`). Tipografía pequeña (`small`) + color atenuado para los links intermedios.
+- Último ítem (la vista actual) no es link; se destaca en negrita o color del texto base.
+- Derivados del router (no escritos a mano por vista) — para que nunca queden desincronizados con la URL real.
+
+---
+
+## 6. Tabs dentro de una sección
+
+Cuando un módulo tiene 2-3 sub-vistas relacionadas (p. ej. "Sucursales" + "Carga masiva", o "Roles" + "Permisos"), usar tabs en vez de ítems separados del sidebar.
+
+```html
+<ul class="nav nav-tabs mb-4 px-2 bg-white rounded-top">
+  <li class="nav-item">
+    <a class="nav-link" routerLink="./roles" routerLinkActive="active">Roles</a>
+  </li>
+  <li class="nav-item">
+    <a class="nav-link" routerLink="./permisos" routerLinkActive="active">Permisos</a>
+  </li>
+</ul>
+<router-outlet></router-outlet>
+```
+
+**Reglas:**
+
+- **Tabs con routing** (`routerLink` + `routerLinkActive`) — cada tab es una URL propia, bookmarkeable y con back button funcional.
+- Evitar tabs con estado local (`[tab]="currentTab"` sin routing) cuando las sub-vistas son no triviales; el usuario pierde su lugar al recargar.
+- Máximo 3-4 tabs por sección. Si hay más, probablemente son módulos independientes que merecen sidebar.
+
+**[shared-candidato]:** el componente shared `nav-tabs` existe pero se usa mezclando los dos enfoques (routing vs state local). Documentar qué enfoque gana (routing) y migrar los que están en state local.
+
+---
+
+## 7. Back navigation
+
+Para vistas que abren desde un listado (p. ej. `admin/usuario` → `admin/usuario/editar/:id`), ofrecer retorno explícito al listado:
+
+- **Opción A (recomendada):** link "← Volver a usuarios" en la parte superior del header, alineado con el título.
+- **Opción B:** botón `Cancelar` en el footer del formulario que navega a la ruta padre.
+
+**Reglas:**
+
+- El back siempre navega a la ruta **explícita** (router a `/admin/usuario`), no `history.back()` (comportamiento impredecible si el usuario llegó por deep link o recarga).
+- Usar un helper compartido para resolver la "ruta padre" desde la ruta actual (evita hardcodear). 
+
+**[shared-candidato] `back-button`** — observado reinventado en 3+ lugares (`volverHome()` en sidebar, `irHome()` en header, similar en sucursal). Extraer a un componente o servicio.
+
+---
+
+## 8. Routing: lazy loading y rutas anidadas
+
+Cada módulo admin (usuario, sucursal, producto, accesos, etc.) vive como **módulo Angular lazy-loaded** bajo el layout padre:
+
+```ts
+{ path: 'usuario', loadChildren: () => import('./usuario/usuario.module').then(m => m.UsuarioModule) }
+```
+
+Cada módulo hijo define sus rutas anidadas (`lista`, `nuevo`, `editar/:id`, sub-tabs, modales con estado en URL si aplica).
+
+**Reglas:**
+
+- El layout admin (`admin-layout.component`) envuelve todas las rutas hijas con `<router-outlet>`, de forma que sidebar y toolbar persistan entre navegaciones.
+- Default redirect por módulo: `{ path: '', redirectTo: 'lista' }` para que `/admin/usuario` abra automáticamente el listado.
+- Guards a nivel de layout (autenticación, sesión) — no repetir en cada ruta hija.
+
+Detalles técnicos y ejemplo completo del routing: `coding-standards/references/angular-typescript.md` y `coding-standards/references/frontend-structure.md`.
+
+---
+
+## 9. Stack del proyecto
+
+El proyecto usa **Angular + Bootstrap + ng-bootstrap**:
+
+- **Sidebar/toolbar:** componentes dedicados en `@presentation/admin/layout/` (`admin-layout`, `sidebar`, `toolbar`). Consumen `MenuCatalogService` para el catálogo dinámico.
+- **Tabs:** usar `nav-tabs` shared con `routerLink` + `routerLinkActive="active"`. La variante state-local existe pero es legado — no replicar.
+- **Breadcrumbs:** hay lógica en `AdminStore.breadcrumbs` (computed signal) pero **no se renderiza en la UI actual**. Si se activa, conectar el computed al template en `admin-layout`.
+- **wizard-footer** shared existe pero no se usa en admin. Reservado para futuros flujos multi-step.
+
+---
+
+## 10. Checklist de replicación
+
+Al añadir un módulo nuevo bajo admin:
+
+- [ ] Lazy loading como módulo Angular (`loadChildren`).
+- [ ] Añadir ítem en el catálogo de menú (`MenuCatalogService`) con nombre, ícono y ruta.
+- [ ] Rutas anidadas dentro del módulo: `lista`, `nuevo`, `editar/:id` como mínimo.
+- [ ] Default redirect del módulo → `lista`.
+- [ ] Page header consistente en cada vista (`h2 fw-bold` + descripción + acción).
+- [ ] Si hay sub-vistas relacionadas, tabs con routing (no state local).
+- [ ] Back navigation explícito en las vistas de edición.
+- [ ] Sidebar/toolbar se heredan del layout padre — no crear otros.
+- [ ] Guards de sesión/autenticación a nivel de layout.
+- [ ] Revisar `shared/` antes de crear helpers de navegación.

package/skills/agent-workflow/standards/redaccion-simple/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: redaccion-simple
+description: "Guía transversal de redacción para artefactos qtc-*. Reglas para escribir OBJECTIVE/TASKS/DECISIONS/EVIDENCE/FINDINGS/CONCLUSIONS/CHECKPOINT/STATUS/PROBLEM/IDEAS/DELIVERY (legacy ES = OBJETIVO/DECISIONES/EVIDENCIA/HALLAZGOS/CONCLUSIONES/PROBLEMA/ENTREGA) con frases cortas, listas sobre prosa, sin jerga. Activable cross-plugin como `agent-workflow:redaccion-simple`. Aplica a toda prosa que el AI produzca en contexto qtc-*: artefactos `.md` de sesión, mensajes de commit, descripciones de PR, READMEs ad-hoc, respuestas en chat sobre temas qtc-*. No requiere sesión activa."
+version: 2.0.1
+---
+
+# Redacción simple — Guía transversal qtc-*
+
+Reglas de estilo y formato para los artefactos que producen los plugins qtc-* (core, dev, design, analyze).
+
+## Cuándo se invoca
+
+- Implícitamente al escribir cualquier `.md` dentro de una sesión qtc-* (artefactos canónicos).
+- Implícitamente al producir prosa en contexto qtc-* fuera de sesión activa: commit messages, descripciones de PR, READMEs ad-hoc, respuestas en chat sobre runtime/skills/sesiones qtc-*.
+- Explícitamente con `Skill(agent-workflow:redaccion-simple)` desde un flow plugin o desde la skill agregadora `agent-workflow:rules`.
+- Referenciada desde `session`, `compact`, `resume` y los skills de los flow plugins.
+
+## Las 6 reglas
+
+1. **Frases cortas**: máximo ~15 palabras. Si pasa de 20, partir en dos.
+2. **Listas sobre prosa**: 3+ ideas paralelas van en bullets. Prosa solo para narrar.
+3. **Una idea por línea**: si el bullet usa "y" o ";" para meter una segunda idea, separar.
+4. **"Qué + por qué" en una línea**: formato `<qué>: <por qué corto>`. Sin párrafo aparte para el "por qué".
+5. **Sin jerga ni abreviaturas raras**: palabras comunes. Términos técnicos (MCP, C4) OK; abreviaturas inventadas (ej. "TLDR del CTX") no.
+6. **Sin relleno**: borrar "es importante notar que…", "cabe destacar…", "como se mencionó…", "en conclusión…". La idea va directo.
+
+## Palabras a evitar / preferir
+
+| Evitar | Preferir |
+|---|---|
+| "es importante notar que" | (borrar y empezar con la idea) |
+| "cabe destacar" | (borrar) |
+| "en otras palabras" | (borrar) |
+| "se procede a" | "vamos a" / verbo directo |
+| "implementar la funcionalidad de X" | "implementar X" |
+| "realizar la validación de" | "validar" |
+| "llevar a cabo" | "hacer" |
+| "a los efectos de" | "para" |
+| "en el marco de" | "en" |
+| "asimismo" | "también" |
+| "no obstante" | "pero" |
+| "previamente mencionado" | "antes" / "ya dicho" |
+| "TLDR", "FYI", "WIP" | escribir la palabra completa |
+
+## Ejemplos antes / después
+
+**1. Prosa redundante**
+
+Antes:
+> Es importante notar que los MCPs `<mcp-cert>` y `<mcp-prod>` constituyen hoy la única vía de acceso a la información de schema desde las sesiones de Claude Code. En el marco de la operatoria habitual, cada llamada implica un round-trip al servidor MCP además del consumo de tokens correspondiente al JSON de respuesta.
+
+Después (-50%):
+> Hoy las sesiones acceden al schema solo vía MCP `<mcp-cert>` y `<mcp-prod>`. Cada llamada cuesta un round-trip y los tokens del JSON.
+
+**2. Decisión densa**
+
+Antes:
+> Se decidió, luego de analizar las distintas alternativas, implementar la validación de roles a nivel del frontend exclusivamente, dado que el backend de mantenimiento no requiere conocer la lógica de permisos para operar correctamente, y además esto evita duplicar la regla de negocio en dos lugares distintos.
+
+Después:
+> **Decisión**: validar permisos solo en el frontend.
+> **Por qué**: el backend de mantenimiento no necesita la lógica; evita duplicar la regla.
+
+**3. Tarea con código inline**
+
+Antes:
+> - [ ] **T3**: Implementar el método `validarRol`.
+>   ```java
+>   public boolean validarRol(Usuario u, Rol r) {
+>     if (u == null) throw new IllegalArgumentException("...");
+>     ...
+>   }
+>   ```
+
+Después:
+> - [ ] **T3**: Implementar `validarRol(Usuario, Rol)` en `RolService`. Hecho cuando devuelve `true` para la matriz de `EVIDENCE.md § matriz-roles`.
+
+## Cuándo SÍ se permite prosa larga
+
+- `## Summary` de CONCLUSIONS.md (modality=technical): si la decisión necesita 4-6 oraciones para sostenerse.
+- Conclusión de causa raíz dentro de CONCLUSIONS.md (modality=incident): la cadena causal puede requerir un párrafo.
+- `## UX decisions` de DELIVERY: cuando explicar un tradeoff visual.
+
+En esos casos sigue aplicando "frases cortas": prosa de oraciones simples encadenadas, no oraciones largas.
+
+## Estructuras mínimas por artefacto
+
+Cada artefacto tiene una estructura fija. Cambia el contenido, no los headings que los parsers leen.
+
+| Artefacto | Headings | Tamaño objetivo |
+|---|---|---|
+| OBJECTIVE.md (legacy: OBJETIVO.md) | `## <Modality\|Type\|Requirement>`, `## <Question\|Brief\|Requirement>`, `## Context`, `## Acceptance criteria`, `## Origin` (opcional), `## Topics` (opcional dev) | 30-60 líneas |
+| TASKS.md | `## Plan summary`, `## Tasks`, `## Risks / external dependencies` | 40-100 (full); 20-40 (lite) |
+| DECISIONS.md (legacy: DECISIONES.md) | `## DEC-NNN: <título>` con `**Decisión**:` + `**Por qué**:` + opcionales | 3-6 líneas por decisión |
+| STATUS.md | campos planos + `## Branches por fuente`, `## Next step` o `## Cierre` | 15-25 líneas |
+| CHECKPOINT.md | `## Last action`, `## Next step`, `## Recent decisions`, `## Files touched`, `## Critical context to resume`, `## Refs` | 20-50 líneas |
+| EVIDENCE.md (legacy: EVIDENCIA.md) | `## Original question`, `## Sources consulted`, `## Raw finding N: <título>`, `## Notes / tentative hypotheses` | 40-150 líneas |
+| FINDINGS.md (legacy: HALLAZGOS.md) | `## Patterns identified`, `## Model decision`, `## What is NOT known (gaps)`, `## False positives discarded` (opcional) | 30-100 líneas |
+| CONCLUSIONS.md (cualquier modality, legacy: CONCLUSIONES.md) | `## Modality`, `## Summary`, `## Conclusions`, `## Recommendations`, `## Traceability`, `## Open` (opcional) | 60-200 líneas según modality y profundidad |
+| PROBLEM.md (legacy: PROBLEMA.md) | `## Statement`, `## Key constraints`, `## Success metrics` | 20-50 líneas |
+| IDEAS.md | `## Variant A/B/C` con Idea/Pros/Contras, `## Initial recommendation` | 60-120 líneas |
+| DELIVERY.md (legacy: ENTREGA.md) | `## Summary`, `## Components` (con `### <Component>`), `## Flows / interactions`, `## UX decisions`, `## Out of scope` | 150-300 líneas |
+
+Tamaño objetivo es **suave**: pasarlo está OK si se justifica.
+
+## Reglas operativas por artefacto
+
+- **OBJECTIVE**: `## Context` arranca con "Lo que NO está en la pregunta:". Sin sección `## Restricciones` separada.
+- **TASKS**: prohibido código inline. Si hace falta código, va en EVIDENCE y se referencia.
+- **DECISIONS**: si una DEC-NNN es obvia, no se registra. Sin SQL/código inline.
+- **STATUS**: sin `## Artefactos` enumerando archivos (`ls` ya lo hace). Sin `## Handoff sugerido` separado.
+- **CHECKPOINT**: si una sección no aplica, se borra entera. Sin placeholders vacíos.
+- **EVIDENCE**: cada hallazgo 4-8 líneas. Tablas solo si comparan más de 3 cosas.
+- **CONCLUSIONS**: sin `## Context` que repita el OBJECTIVE. Sin opciones falsas tipo "no hacer nada". Sin pseudocódigo. Cada `**CN**` con evidencia link; cada `**RN**` con responsable + cuándo.
+
+## Sandbox read-only
+
+Canon universal en `../session/references/sandbox-readonly-rules.md`. Esta skill es read-only por diseño — carga reglas de redacción, no escribe artefactos por sí misma. Los skills consumidores (`session`, `compact`, `resume`, etc.) son quienes producen el `.md`.
+
+En plan mode: describir en el plan file qué artefacto se redactaría (OBJECTIVE / TASKS / DECISIONS / EVIDENCE / FINDINGS / CONCLUSIONS / CHECKPOINT / STATUS / commit-msg / PR-description), qué reglas operativas aplican, y el tamaño objetivo en líneas. NO ejecuta `Write`, `Edit`, `MultiEdit` por sí misma — describe el contenido para que el consumidor lo materialice.
+
+Compatible con plan mode sin restricciones adicionales.
+
+## Referencias
+
+- Propuesta origen: `agent-workflow/docs/propuestas/001-simplificar-artefactos.md` (graduado de session005-analyze; el repo legacy era `core-workflow-plugin`).
+- Templates afectados: `agent-workflow-cli/src/application/templates/objective.ts` (canon EN; ES legacy `OBJETIVO.md` sigue siendo legible vía bilingual readers R1).
+- Skills consumidores: `session`, `compact`, `resume`, y los workflows `dev-workflow`/`design-workflow`/`analyze-workflow` (todos en `agent-workflow`).

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

@@ -0,0 +1,197 @@
+---
+name: sql-rollback-generator
+description: "Genera rollback **post-hoc** desde SCRIPTS.sql consolidado (v1.0.0 BREAKING — F-D session062): cuando /agent-workflow:export-scripts separa el bundle, este skill produce `.rollback.sql` por sentencia forward + `rollback-global.sql` encadenado en orden inverso (04→03→02→01). Cubre DDL (DROP IF EXISTS), migraciones con backup en esq_audit, e inserts. Marca operaciones irreversibles (DROP COLUMN, TRUNCATE, DROP CASCADE) con header WARNING. BREAKING desde v1.0.0: deja de generar rollbacks durante exec por archivo; la generación ocurre exclusivamente al exportar."
+version: 1.0.0
+---
+
+# SQL Rollback Generator (v1.0.0 — on-export)
+
+Generación de rollbacks **post-hoc** desde el archivo único `SCRIPTS.sql` de cada sesión. Disparado por `/agent-workflow:export-scripts` v3.0.0+ al producir el bundle de release.
+
+> **BREAKING desde v1.0.0**: este skill ya NO genera `.rollback.sql` durante la sesión. La política previa "on-write per archivo" (v0.x) generaba un rollback acoplado por cada forward; la política nueva "on-export" agrupa la generación al consolidar el bundle. Razón: el flujo SQL durante exec ahora es un único `SCRIPTS.sql` (ver `sql-script-organizer` v1.0.0); no hay archivos individuales que parear con rollbacks. Layouts legacy se migran con `/agent-workflow:migrate --upgrade-topology`.
+
+## When to use
+
+- **Disparado por `/agent-workflow:export-scripts`** al consolidar el bundle desde N sesiones.
+- NL del usuario: "generar rollback", "script de reversa", "rollback global".
+- Si el usuario quiere entender cómo revertir un cambio específico ANTES del export: este skill puede simular un rollback en plan-mode sin escribir archivos.
+
+## Sandbox read-only
+
+Reglas en `../session/references/sandbox-readonly-rules.md`. En plan mode describir estrategia por sentencia forward (sin crear `.rollback.sql`); irreversibles se anotan para revisión.
+
+## Principios (v1.0.0)
+
+- **Input**: `SCRIPTS.sql` de cada sesión incluida en el corpus de export, parseado vía markers `@category`/`@stmt` (ver `sql-script-organizer/references/scripts-sql-format.md`).
+- **Output**: archivos `.rollback.sql` ubicados junto al forward separado en el bundle export (`por-sesion/sessionXXX/<categoria>/NNN-*.rollback.sql`).
+- **Global**: `por-sesion/sessionXXX/rollback/00-rollback-global.sql` encadena los rollbacks en orden inverso (04 → 03 → 02 → 01), todo en `BEGIN; ... COMMIT;` único.
+- **Idempotencia obligatoria**: `DROP ... IF EXISTS`, `CREATE OR REPLACE`, `ON CONFLICT DO NOTHING`.
+- **Transacción obligatoria** en cada rollback individual.
+- **Header del rollback** reusa el del forward (4 líneas Script/Sesion/Objeto/Alcance) con `Objeto:` describiendo la reversa.
+- **Irreversibles** (DROP COLUMN, TRUNCATE, DROP CASCADE, datos sin backup) marcados con `-- WARNING: IRREVERSIBLE` debajo del header.
+- **Datos**: si el forward es UPDATE/DELETE masivo sin backup, generar un `000-backup-*.sql` previo en el bundle (Categoría 03-migracion) + rollback que restaure desde `esq_audit.tb_bkp_<x>_sNNN`.
+
+## Header del rollback
+
+El `.rollback.sql` reusa el mismo formato canónico definido en `sql-script-organizer/SKILL.md#header-canónico`:
+
+```sql
+-- ============================================================================
+-- Script:  NNN-tipo-objetivo.rollback.sql
+-- Sesion:  sNNN
+-- Objeto:  Revierte los cambios de NNN-tipo-objetivo.sql (<resumen de la reversa>).
+-- Alcance: <mismo alcance que el forward>
+-- ============================================================================
+```
+
+- `Objeto:` describe la reversa, no el forward (ej. "Repone tb_x.cod_usuario al valor de esq_audit.tb_bkp_x_sNNN").
+- `Alcance:` repite literal el del forward para que quede explícito que la reversa cubre exactamente el mismo set.
+- Si el forward es irreversible, agregar **debajo del header** una línea suelta:
+
+  ```sql
+  -- ============================================================================
+  -- Script:  ...
+  -- Sesion:  ...
+  -- Objeto:  ...
+  -- Alcance: ...
+  -- ============================================================================
+  -- WARNING: IRREVERSIBLE — best-effort, ver DECISIONS.md DEC-NNN (legacy: DECISIONES.md).
+  ```
+
+  El bloque WARNING explica qué no se puede recuperar y referencia la decisión.
+
+## Estrategias por tipo de operación
+
+### DDL de tablas
+
+| Forward | Rollback |
+|---|---|
+| `CREATE TABLE IF NOT EXISTS esq_.tb_x` | `DROP TABLE IF EXISTS esq_.tb_x;` |
+| `ALTER TABLE tb_x ADD COLUMN col_y ...` | `ALTER TABLE tb_x DROP COLUMN IF EXISTS col_y;` |
+| `CREATE INDEX idx_... ON tb_x(col)` | `DROP INDEX IF EXISTS idx_...;` |
+| `CREATE SEQUENCE esq_.seq_tb_x` | `DROP SEQUENCE IF EXISTS esq_.seq_tb_x;` |
+| `DROP TABLE tb_x` | Backup previo en `esq_audit.tb_bkp_x_sessionXXX`; rollback es `CREATE TABLE ... AS SELECT * FROM esq_audit.tb_bkp_x_sessionXXX` |
+| Reconstrucción | Script previo `000-backup-tb-x.sql` que copia a `esq_audit`; rollback restaura desde backup |
+
+### DDL de funciones y SP
+
+| Forward | Rollback |
+|---|---|
+| `CREATE OR REPLACE FUNCTION fn_x(...)` | `DROP FUNCTION IF EXISTS fn_x(<firma>);` o recrear versión previa con `CREATE OR REPLACE` embebido |
+| `CREATE OR REPLACE PROCEDURE sp_x(...)` | `DROP PROCEDURE IF EXISTS sp_x(<firma>);` + recreación si existe versión anterior |
+| `DROP FUNCTION fn_x` | `-- WARNING: IRREVERSIBLE` — incluir cuerpo en comentario |
+
+### Migración de datos (UPDATE / DELETE)
+
+Pasos obligatorios antes del forward:
+
+1. Generar `000-backup-<tabla>.sql` que copia filas afectadas a `esq_audit.tb_bkp_<tabla>_sessionXXX`.
+2. Rollback usa el backup:
+
+```sql
+BEGIN;
+UPDATE esq_.tb_x t
+SET col_a = bkp.col_a, col_b = bkp.col_b
+FROM esq_audit.tb_bkp_x_sessionXXX bkp
+WHERE t.id_x = bkp.id_x;
+COMMIT;
+```
+
+Si DELETE masivo, rollback es `INSERT INTO ... SELECT * FROM esq_audit.tb_bkp_...`.
+
+### Inserts de datos nuevos
+
+```sql
+BEGIN;
+DELETE FROM esq_.tb_maestras WHERE campo_identificador IN (<lista>);
+COMMIT;
+```
+
+Usar claves naturales o rango de IDs conocido — nunca DELETE sin WHERE.
+
+### Operaciones irreversibles
+
+Marcar con `-- WARNING: IRREVERSIBLE` en el header del forward:
+
+- `TRUNCATE TABLE`
+- `DROP COLUMN` sin respaldo previo
+- `DROP TABLE` sin respaldo previo
+- `ALTER COLUMN TYPE` con pérdida de precisión
+- Cascadas destructivas (`DROP ... CASCADE`)
+- `DELETE` sin respaldo en `esq_audit`
+
+Protocolo:
+
+1. Header WARNING.
+2. Registrar decisión en DECISIONS.md (legacy: DECISIONES.md) antes de ejecutar.
+3. Generar rollback "best-effort" indicando qué se perdería.
+4. **Confirmación explícita** del usuario antes de continuar.
+
+Lista completa en `references/irreversible-checklist.md`.
+
+## Layout (post-export-scripts v3.0.0)
+
+### Par acoplado
+
+`export-scripts` produce los archivos separados desde SCRIPTS.sql y este skill genera el rollback junto a cada forward:
+
+```
+<docs>/scripts/NNN-export-scripts-YYYY-MM-DD/por-sesion/sessionXXX/01-ddl-tablas/
+├── 001-crea-tb-x.sql              (forward, derivado de @stmt en SCRIPTS.sql)
+└── 001-crea-tb-x.rollback.sql     (rollback, generado por este skill)
+```
+
+### Bundle global
+
+```
+<docs>/scripts/NNN-export-scripts-YYYY-MM-DD/por-sesion/sessionXXX/rollback/
+├── 00-rollback-global.sql      (encadena todos 04→01 con BEGIN/COMMIT único)
+├── 04-inserts-rollback.sql
+├── 03-migracion-rollback.sql
+├── 02-ddl-funciones-rollback.sql
+└── 01-ddl-tablas-rollback.sql
+```
+
+Layout pre-v1.0.0 (`scripts/bundle/...` dentro de la sesión durante exec) ya no se genera. Layouts legacy se migran con `/agent-workflow:migrate --upgrade-topology`.
+
+## Proceso
+
+1. Leer el forward — identificar tipo.
+2. Clasificar — seleccionar estrategia.
+3. Generar rollback acoplado.
+4. Verificar irreversibilidades — warning + DECISIÓN + confirmación si aplica.
+5. Actualizar bundle global.
+6. Verificar cobertura antes de graduar.
+
+## Notas de portabilidad (PostgreSQL como motor primario)
+
+| Concepto | PostgreSQL | Oracle | SQL Server |
+|---|---|---|---|
+| Rollback de función | `DROP FUNCTION IF EXISTS fn(...sig)` | `DROP FUNCTION fn` | `DROP FUNCTION IF EXISTS fn` |
+| Idempotencia create | `CREATE OR REPLACE FUNCTION` | `CREATE OR REPLACE FUNCTION` | `CREATE OR ALTER PROCEDURE` |
+| Insertar sin duplicar | `ON CONFLICT DO NOTHING` | `INSERT ... WHERE NOT EXISTS` | `IF NOT EXISTS (SELECT 1 ...) INSERT` |
+| Secuencia | `DROP SEQUENCE IF EXISTS seq_` | `DROP SEQUENCE seq_` | No aplica (IDENTITY) |
+
+Si el destino no es Postgres, indicarlo en `Objeto:` o como nota libre debajo del header (no como campo nuevo).
+
+## Graduación al cierre
+
+`rollback/` viaja junto al bundle forward bajo `docs/scripts/NNN-sessionXXX-nombre/rollback/`.
+
+## Modo release (cross-session + por tema)
+
+`release` y `release-scripts` invocan este skill para producir rollback global del release y rollback por tema. Algoritmo detallado (3 niveles, principios, qué NO hacer, verificación) en **`references/release-rollback.md`**.
+
+## Integración con otros skills
+
+- **`sql-script-organizer`** — companion: organiza el bundle forward y coordina rollbacks. En modo release, provee bundle consolidado.
+- **`release`** — consume rollback global de release.
+- **`release-scripts`** — consume rollback por tema.
+- **`coding-standards`** — reglas de estilo SQL en `database-conventions.md#estilo-de-scripts-sql`.
+- **`session`** — Fase 3 invoca este skill junto a `sql-script-organizer` al escribir el primer `.sql`.
+
+## Recursos adicionales
+
+- **`references/rollback-patterns.md`** — recetas completas con ejemplos SQL.
+- **`references/irreversible-checklist.md`** — lista de irreversibles y protocolo.
+- **`references/release-rollback.md`** — algoritmos de rollback global y por tema (modo release).