@tacuchi/agent-workflow-cli 6.2.0 → 7.0.1

package/skills/agent-workflow/standards/coding-standards/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: coding-standards
+description: Estándares de código por stack (Java/Spring, Angular, Node) — fail-fast, logging por nivel, seguridad (no secrets, SQL parametrizado), naming descriptivo, manejo de errores, validación de input, reglas FE-BE (Sparse DTO unificado, PATCH semantics, sin fallbacks ocultos). Activar al implementar, revisar o refactorizar, o ante NL como buenas prácticas/código limpio/cómo valido este input. Referencia transversal sin dependencia de sesiones.
+version: 0.4.0
+---
+
+> **Profile parametrization**: lee `mcp_databases[] + examples_path` de `profile.json` (resuelto vía cascade 5 capas). Ver [`references/profile-parametrization.md`](../../references/profile-parametrization.md) para el contrato completo y comportamiento por defecto cuando el profile está vacío.
+
+# Coding Standards
+
+Estándares de código aplicables durante la implementación. Consultar la referencia del stack correspondiente para detalles.
+
+## Principios generales
+
+- **SOLID** — Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion
+- **Fail fast** — Validar y retornar errores al inicio del método (early returns, evitar nesting)
+- **Nombres descriptivos** — El código habla por sí mismo; comentarios solo para el "por qué"
+- **Métodos pequeños** — Una sola responsabilidad por método/función
+- **Composición sobre herencia**
+- **Reutilización antes que duplicación (DRY)** — antes de crear un componente, función o clase nueva, revisar si ya existe en `shared/` (frontend) o el paquete `common/`/`util/` (backend). Si un patrón aparece 2-3 veces, proponer extracción. Aplica transversalmente; para detalles de componentes frontend y `shared/`, ver skill `frontend-design` + `references/frontend-structure.md`.
+
+## Estándares por stack
+
+### Java / Spring Boot
+Constructor Injection (sin Field Injection), `@Transactional(readOnly=true)` para lecturas, Java records para DTOs Request/Response, Jakarta Validation para inputs. Ver `references/java-spring.md`.
+
+### Angular / TypeScript
+Constructor injection, NgModules, `async` pipe en templates, evitar `any`. Arquitectura `@data`/`@presentation`. Ver `references/angular-typescript.md` y `references/frontend-structure.md`.
+
+## Integración FE-BE (flow=dev v2.6+)
+
+Aplica a sesiones `flow=dev` con `## Type: feature|refactor` y a refactors guiados por `agent-workflow:refactor`. Reglas canónicas en `references/fe-be-integration.md`:
+
+- **R1 — Sparse DTO unificado**: mismo DTO `<Feature>SaveRequest` para create + edit, todos los campos nullable. `null` = "no tocar".
+- **R2 — PATCH para edit**: `@PatchMapping` en BE, `http.patch()` en FE. POST queda solo para create. PUT no se usa salvo replace total justificado.
+- **R3 — FE envía solo cambios**: payload diff entre `formValue` y entidad original.
+- **R4 — Sin fallbacks que oculten errores**: prohibido `catchError(() => of([]))` en FE; prohibido try/catch con fallback al método legacy en BE durante migraciones. Usar feature flags explícitas si se necesita rollout gradual.
+- **R5 — Validación BE con Bean Validation + groups**: `@NotNull(groups = OnCreate.class)` para distinguir reglas POST vs PATCH cuando comparten DTO.
+- **R6 — DB stub-first**: funciones/SP nuevas arrancan en Phase 0 devolviendo mock (`RETURN '[]'::jsonb`); implementación real recién en Phase 1/2.
+
+## Seguridad
+
+- **Nunca** exponer secrets, API keys o credenciales en código
+- **Nunca** logear datos sensibles (contraseñas, tokens, datos personales)
+- **Siempre** parametrizar queries SQL (nunca concatenar strings)
+- **BD vía MCP** — `<mcp-cert>` (pruebas) y `<mcp-prod>` (producción) son READONLY. Modificaciones a BD solo mediante scripts SQL versionados en `docs/scripts/` del workspace de la fuente; el usuario es quien aplica el script (no el AI), nunca ejecución directa via MCP, Bash, psql ni cualquier otro canal. Excepción única: el usuario explícitamente pide "ejecutalo vos contra cert" — aún así, confirmación por bloque y no asumir autorización ampliada
+
+## Manejo de errores HTTP
+
+- **Nunca silenciar errores HTTP con `catchError(() => of([]))` ni equivalentes.** Los errores del backend se propagan al usuario vía toast/mensaje; solo así detectamos regresiones durante guardado, sincronizaciones y creaciones. Si hace falta lógica de reintento, usar operadores RxJS explícitos (`retry`, `retryWhen`), no silenciar.
+
+## Logging
+
+- `ERROR` — Fallos que requieren atención inmediata
+- `WARN` — Situaciones inesperadas pero manejadas
+- `INFO` — Eventos de negocio relevantes (inicio/fin de procesos)
+- `DEBUG` — Detalle técnico para diagnóstico
+
+## Git y ramas
+
+Política de commits: ver `agent-workflow:commits-policy` (canónico).
+
+### Estrategia de ramas
+- **`certificacion`** — Rama principal/producción. Base para crear feature branches.
+- **`desarrollo`** — Rama QA. Solo para probar features desplegados. Se sincroniza desde `certificacion`. No se usa como base.
+- **Feature branches** — Siempre desde `certificacion`, PR hacia `certificacion`.
+
+### Prefijo opcional Conventional Commits
+
+Si la sesión/equipo lo prefiere, se puede combinar con el formato canónico:
+
+- `feat(session<NNN>):` nueva funcionalidad
+- `fix(session<NNN>):` corrección de bug
+- `docs(session<NNN>):` documentación
+- `chore(session<NNN>):` mantenimiento, dependencias
+- `refactor(session<NNN>):` reestructuración sin cambio funcional
+
+Ramas: `feature/`, `fix/`, `hotfix/` + descripción-kebab-case.
+
+## Sandbox read-only
+
+Canon universal en `../session/references/sandbox-readonly-rules.md`. Esta skill es read-only por diseño — carga estándares de código por stack y reglas FE-BE, no edita ni ejecuta nada.
+
+En plan mode: describir en el plan file qué reglas se aplicarían al edit/refactor propuesto (fail-fast, FE-BE R1-R6, MCP READONLY, SQL parametrizado) y listar los refs relevantes (Java/Spring, Angular/TypeScript, fe-be-integration). NO ejecuta `Write`, `Edit`, `MultiEdit`, `Bash` con efectos colaterales, ni queries MCP mutantes.
+
+Compatible con plan mode sin restricciones adicionales.
+
+## Recursos adicionales
+
+### Archivos de referencia
+- **`references/fe-be-integration.md`** — Reglas FE-BE (Sparse DTO unificado, PATCH, sin fallbacks ocultos, Bean Validation con groups, DB stub-first). Aplica a `## Type: feature|refactor`.
+- **`references/java-spring.md`** — Convenciones Java/Spring Boot (inyección, records, transacciones, validación) + PATCH+Sparse DTO con records.
+- **`references/angular-typescript.md`** — Convenciones Angular/TypeScript (constructor injection, NgModules, ApiService) + PATCH client + interfaces sparse.
+- **`references/frontend-structure.md`** — Arquitectura `@data`/`@presentation`, ApiService, interfaces espejeo backend, environments, build
+- **`references/database-conventions.md`** — Nomenclatura BD: esquemas `esq_`, tablas `tb_`, columnas, sequences, funciones `fn_`/`sp_`, patrón maestra-detalle, auditoría, estilo de scripts SQL (transacciones, CTE, comentarios, idempotencia)
+- **`references/project-structure.md`** — Estructura de paquetes backend, capas Entity→Repository→Service→Controller, wrappers `ReqBase`/`RespBase`, convención DTOs `P`/`R`/`Req`
+- **`../frontend-design/`** — Principios de diseño UX para formularios de mantenimiento (agnóstico a framework) + reutilización de componentes y framework-first CSS. Consultar en paralelo con `angular-typescript.md` cuando el trabajo es frontend de mantenimiento.
+
+### Skills de base de datos
+Cuando el stack involucra BD y se escriben scripts SQL:
+- **`sql-script-organizer`** — Organiza scripts en 4 categorías, aplica estilo y genera bundle listo para producción
+- **`sql-rollback-generator`** — Genera rollback acoplado por script y bundle global de reversión

package/skills/agent-workflow/standards/coding-standards/references/angular-typescript.md

@@ -0,0 +1,266 @@
+# Angular / TypeScript — Convenciones detalladas
+
+## Inyección de servicios
+
+Los proyectos actuales usan constructor injection con `private`:
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class SolicitudService {
+  constructor(private apiService: ApiService) {}
+}
+
+@Component({ ... })
+export class MiComponente {
+  constructor(
+    private solicitudService: SolicitudService,
+    private router: Router
+  ) {}
+}
+```
+
+> **Nota**: `inject()` es válido en Angular 14+ y preferible en proyectos nuevos, pero seguir la convención del proyecto actual.
+
+## NgModules
+
+Los proyectos usan NgModules con routing modules separados:
+
+```typescript
+@NgModule({
+  declarations: [AppComponent],
+  imports: [
+    BrowserModule,
+    AppRoutingModule,
+    ComponentsModule,
+    SharedModule,
+    ToastrModule.forRoot(),
+    BrowserAnimationsModule
+  ],
+  bootstrap: [AppComponent]
+})
+export class AppModule {}
+```
+
+> **Nota**: Standalone components son válidos en Angular 15+ pero los proyectos actuales no los usan. No migrar a standalone a menos que el usuario lo pida.
+
+## Async pipe en templates
+
+Preferir async pipe sobre subscribe manual para datos del template:
+
+```html
+<div *ngIf="solicitudes$ | async as solicitudes">
+  <app-tabla [data]="solicitudes"></app-tabla>
+</div>
+```
+
+```typescript
+solicitudes$ = this.solicitudService.listar();
+```
+
+## Tipos estrictos
+
+Evitar `any`. Usar interfaces en `@data/interfaces/`:
+
+```typescript
+// Interfaces que espejean el backend
+export interface IResponsePayload<T> {
+  trace: Trace;
+  status: Status;
+  payload: T;
+}
+
+export interface ResponseDTO {
+  identificador: number;
+  cuerpo: string;
+  mensaje: string;
+}
+
+// Incorrecto
+const data: any = response.body;  // NO
+```
+
+## Estructura de proyecto
+
+Ver `references/frontend-structure.md` para la arquitectura completa `@data`/`@presentation`.
+
+## PATCH + Sparse DTO unificado (qtc-dev v2.6+)
+
+Para mantenimientos CRUD seguir las reglas de `references/fe-be-integration.md`:
+
+- **Interface única** `<Feature>SaveRequest` para create + edit con campos opcionales (`?` o `| null`).
+- **POST** envía todos los required cargados; **PATCH** envía solo los campos modificados (resto omitido).
+- ApiService expone `patch<T>(url, body)` paralelo a `post<T>(url, body)`.
+
+```typescript
+export interface CategoriaSaveRequest {
+  nombre?: string | null;
+  descripcion?: string | null;
+  activo?: boolean | null;
+  ordenVisual?: number | null;
+}
+
+@Injectable({ providedIn: 'root' })
+export class CategoriasService {
+  constructor(private apiService: ApiService) {}
+
+  create(req: CategoriaSaveRequest): Observable<IResponsePayload<CategoriaResponse>> {
+    return this.apiService.post(`${env.API_ADMIN}v1/categorias`, req);
+  }
+
+  edit(id: number, cambios: CategoriaSaveRequest): Observable<IResponsePayload<CategoriaResponse>> {
+    return this.apiService.patch(`${env.API_ADMIN}v1/categorias/${id}`, cambios);
+  }
+}
+```
+
+En el componente de edición, construir el payload diff con solo los campos que cambiaron:
+
+```typescript
+guardar(): void {
+  const original = this.categoriaOriginal;
+  const form = this.form.value;
+  const cambios: CategoriaSaveRequest = {};
+  if (form.nombre !== original.nombre) cambios.nombre = form.nombre;
+  if (form.descripcion !== original.descripcion) cambios.descripcion = form.descripcion;
+  if (form.activo !== original.activo) cambios.activo = form.activo;
+  if (form.ordenVisual !== original.ordenVisual) cambios.ordenVisual = form.ordenVisual;
+
+  if (Object.keys(cambios).length === 0) return; // nada cambió
+
+  this.servicio.edit(original.id, cambios).subscribe({
+    next: (res) => this.toast.success('Guardado'),
+    error: (err) => this.errorHandler.handle(err) // R4 — no silenciar
+  });
+}
+```
+
+**Anti-pattern**: enviar `form.value` completo en PATCH equivale a PUT y rompe la semántica sparse. Detalles + casos edge: `references/fe-be-integration.md`.
+
+## Services y API
+
+Todas las llamadas HTTP pasan por `ApiService` (wrapper central en `@data/services/`):
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class SolicitudService {
+  constructor(private apiService: ApiService) {}
+
+  generaSolicitud(solicitud: Solicitud): Observable<IResponsePayload<ResponseDTO>> {
+    const request = armarPayload<any>(solicitud);
+    const url = `${env.API_PRESTAMO}v1/solicitud`;
+    return this.apiService.post(url, request);
+  }
+
+  getOfertas(idSolicitud: number): Observable<IResponsePayload<IPayloadListG<Oferta>>> {
+    const params = requestFilter({ idSolicitud });
+    const url = `${env.API_PRESTAMO}v1/solicitud/listar-ofertas?${params}`;
+    return this.apiService.get(url);
+  }
+}
+```
+
+No usar `HttpClient` directamente en services de presentación.
+
+## Environments
+
+URLs de API se configuran en environment files:
+
+```typescript
+export const environment = {
+  production: false,
+  API_PRESTAMO: '',
+  API_SOLICITUD: '',
+  API_IDENTIDAD: '',
+  API_MOTOR: '',
+};
+```
+
+Archivos: `environment.ts`, `environment.dev.ts`, `environment.prod.ts`
+
+## Build y verificación
+
+- Build producción: `npm run build:prod` (equivale a `ng build -c=production`)
+- Build desarrollo: `npm run build:dev` (equivale a `ng build -c=development`)
+- Serve local: `npm run start:dev`
+- Tests: `ng test --watch=false`
+- Estilos: SCSS
+- UI: Angular Material + Bootstrap
+
+## Formularios reactivos
+
+Patrones al trabajar con `FormGroup` / `FormControl` en mantenimientos CRUD. Para los principios de UX (cuándo usar switch vs checkbox, layout de cards, hints en combos), ver skill `frontend-design`.
+
+### Combo dependiente con carga diferida
+
+Cuando el valor del combo B depende del valor del combo A, suscribirse a `valueChanges` de A en `ngOnInit`:
+
+```typescript
+this.formMantenimiento.get('idPadre')?.valueChanges.subscribe((valor) => {
+  this.formMantenimiento.get('idHijo')?.setValue('');
+  if (valor) {
+    this.listarHijos(String(valor));
+  } else {
+    this.lstHijos = [];
+  }
+});
+```
+
+Al editar, la **precarga inicial** debe setear padre e hijo **sin** disparar el listener (para no perder el valor de hijo que viene del backend):
+
+```typescript
+this.formMantenimiento.patchValue({
+  idPadre: data.idPadre != null ? String(data.idPadre) : '',
+  idHijo:  data.idHijo  != null ? String(data.idHijo)  : ''
+}, { emitEvent: false });
+
+if (data.idPadre) {
+  this.listarHijos(String(data.idPadre));
+}
+```
+
+### Normalización de tipos en controles compartidos
+
+Componentes custom tipo `search-select` o equivalentes suelen comparar opciones con `===`. Si las opciones tienen `value: "1"` (string) pero el DTO trae `1` (number), la opción **no matchea** y el combo queda vacío.
+
+Regla: normalizar consistentemente en el `patchValue`. La forma que expone el componente UI manda:
+
+```typescript
+this.formMantenimiento.patchValue({
+  idRol: data.idRol != null ? String(data.idRol) : ''
+}, { emitEvent: false });
+```
+
+Aplicar la misma regla a todos los campos tipo id. Documentar la decisión si no es obvia.
+
+### Sincronizaciones secuenciales con `concat`
+
+Cuando N operaciones HTTP deben correr **en orden estricto** (evitar race conditions contra restricciones de unicidad del backend), usar `concat` de RxJS, no paralelo:
+
+```typescript
+import { concat, of } from 'rxjs';
+import { toArray } from 'rxjs/operators';
+
+const ops = [
+  ...paraDesactivar.map(r => this.servicio.desactivar(r.id)),
+  ...(nuevoRequerido ? [this.servicio.asignar(nuevo)] : [])
+];
+return ops.length ? concat(...ops).pipe(toArray()) : of([]);
+```
+
+Orden: primero desactivar los sobrantes, luego asignar el nuevo. Nunca paralelo en estos casos.
+
+### Switch Bootstrap alineado
+
+Patrón de clases para que el switch (3em×1.5em) quede alineado verticalmente con su label:
+
+```html
+<div class="form-switch d-flex align-items-center gap-2 ps-0 mb-0">
+  <input type="checkbox" class="form-check-input m-0" role="switch" id="mi-switch"
+         [checked]="activo" (change)="toggle($event)">
+  <label class="form-check-label mb-0" for="mi-switch">Texto del switch</label>
+</div>
+```
+
+Claves: `d-flex align-items-center gap-2` (alinea), `ps-0` (anula padding-left 1.5em default de `.form-check`), `input.m-0` y `label.mb-0` (anulan márgenes que desalinean con el switch grande).
+
+Para la decisión UX **cuándo usar switch vs checkbox**, ver skill `frontend-design` (`references/form-patterns.md` §5).

package/skills/agent-workflow/standards/coding-standards/references/database-conventions.md

@@ -0,0 +1,170 @@
+# Convenciones de Base de Datos
+
+PostgreSQL. Todas las convenciones son snake_case en español.
+
+## Esquemas
+
+Prefijo `esq_` + dominio: `esq_credito`, `esq_seguridad`, `esq_motor`, `esq_contabilidad`, `esq_liquidacion`, `esq_pago`, `esq_movimiento`, `esq_reportes`, `esq_audit`, `esq_sistema`, `esq_pos`, `esq_promocion`, `esq_planeamiento`, `esq_seguro`, `esq_reclamo`, `esq_request`, `esq_kashio`.
+
+Cada microservicio trabaja con 1-2 esquemas. Siempre referenciar el schema explícitamente en queries nativas y en `@Table`.
+
+## Tablas
+
+- Prefijo `tb_` + entidad: `tb_credito`, `tb_cliente`, `tb_solicitud`
+- Relaciones: `tb_pago_cronograma`, `tb_usuario_sucursal`
+- Cabecera/detalle: sufijo `_cab` / `_det` → `tb_lote_cab`, `tb_lote_det`
+
+## Columnas
+
+### Primary Keys
+`id_` + entidad → `id_credito`, `id_cliente`, `id_solicitud`
+
+### Foreign Keys
+Mismo nombre que la PK referenciada → `id_cliente` en `tb_credito` apunta a `tb_cliente.id_cliente`
+
+### Fechas
+`fecha_` + acción → `fecha_registro`, `fecha_modificacion`, `fecha_solicitud`, `fecha_aprobacion`, `fecha_prestamo`
+
+### Montos
+`monto_` + concepto → `monto_prestamo`, `monto_cuota`, `monto_pagar`, `monto_desembolsado`
+
+### Estados
+- `estado` → integer genérico (1=activo, 0=inactivo)
+- `estado_proceso`, `estado_aprobacion` → integer, referencia a `tb_maestra_detalle.id_maestra_detalle`
+
+### Flags
+`flag_` + concepto → `flag_extorno` (integer 0/1)
+
+### Tipos de datos
+- `integer` → IDs, estados, flags
+- `numeric` → montos, tasas, porcentajes
+- `character varying` → textos
+- `timestamp without time zone` → fechas con hora
+- `date` → fechas sin hora
+- `boolean` → flags en tablas más nuevas
+
+## Auditoría
+
+Campos presentes en casi todas las tablas (mapeados por la clase base `Auditoria` en Java):
+
+```
+estado              integer       NOT NULL   -- 1=activo, 0=inactivo
+usuario_registro    varchar       NOT NULL   -- usuario que creó
+fecha_registro      timestamp     NOT NULL   -- cuándo se creó
+usuario_modificacion varchar      NULL       -- usuario última modificación
+fecha_modificacion  timestamp     NULL       -- cuándo se modificó
+```
+
+## Sequences
+
+Patrón: `seq_tb_[entidad]` en el mismo esquema → `esq_credito.seq_tb_credito`
+
+## Índices
+
+- PK: `pk_tb_[entidad]`
+- Índices: `idx_tb_[entidad]_[columna]` o `idx_[entidad]_[columnas]`
+
+## Funciones y Stored Procedures
+
+- Funciones: `fn_` + verbo + sustantivo → `fn_obtener_segmento`, `fn_calcular_cuota_oferta`
+- Procedures: `sp_` + verbo + sustantivo → `sp_genera_credito`, `sp_recalcula_credito`
+- Versionado: sufijo `_v2`, `_v3` para versiones nuevas (no se borran las anteriores)
+
+## Patrón Maestra-Detalle
+
+`tb_maestra` + `tb_maestra_detalle` es el catálogo centralizado. Estados, tipos de documento, tipos de crédito, etc. se referencian vía `id_maestra_detalle`. El campo `codprog` identifica el grupo funcional dentro de la maestra.
+
+Al crear nuevos estados o tipos, siempre usar `tb_maestra_detalle` en lugar de hardcodear valores.
+
+## Estilo de scripts SQL
+
+Reglas de escritura para todos los scripts SQL de la sesión. Aplicar desde el primer `.sql`.
+
+### Transacciones
+
+```sql
+BEGIN;
+-- cuerpo del script
+COMMIT;
+```
+
+`ROLLBACK` explícito en bloques con manejo de errores:
+
+```sql
+DO $$ BEGIN
+    -- lógica
+EXCEPTION WHEN OTHERS THEN
+    RAISE;
+END; $$;
+```
+
+### Idempotencia
+
+| Operación | Forma idempotente |
+|---|---|
+| Crear tabla | `CREATE TABLE IF NOT EXISTS` |
+| Eliminar objeto | `DROP ... IF EXISTS` |
+| Crear/actualizar función | `CREATE OR REPLACE FUNCTION` |
+| Insertar sin duplicar | `INSERT ... ON CONFLICT DO NOTHING` |
+| Actualizar o insertar | `INSERT ... ON CONFLICT DO UPDATE` |
+
+### CTEs sobre subqueries anidados
+
+Usar CTE cuando hay ≥2 joins encadenados o cuando el mismo subquery se reutiliza:
+
+```sql
+-- Evitar:
+SELECT * FROM tb_a WHERE id IN (SELECT id FROM tb_b WHERE id IN (SELECT id FROM tb_c));
+
+-- Preferir:
+WITH ids_c AS (SELECT id FROM tb_c),
+     ids_b AS (SELECT b.id FROM tb_b b JOIN ids_c c ON b.id = c.id)
+SELECT * FROM tb_a a JOIN ids_b b ON a.id = b.id;
+```
+
+### Comentarios ligeros
+
+Header canónico de 4 líneas (Script / Sesion / Objeto / Alcance) entre dos líneas de iguales:
+
+```sql
+-- ============================================================================
+-- Script:  003-ddl-tb-solicitud-credito.sql
+-- Sesion:  s003
+-- Objeto:  Crear tabla de solicitudes de crédito.
+-- Alcance: Esquema esq_credito; sin migración de datos.
+-- ============================================================================
+```
+
+Detalles, separadores entre secciones del cuerpo y la regla "CTEs sobre `DO`/`LOOP`" en `sql-script-organizer/SKILL.md#header-canónico`. Autor / Fecha / Motor / "Defensa futura" no van adentro del header — si el caso lo amerita, van como nota libre en una línea suelta debajo. Solo comentar el **por qué** cuando no es obvio. Nunca documentar qué hace una línea si el nombre ya lo dice.
+
+### Sin funciones utilitarias efímeras
+
+No crear `fn_*` o `sp_*` solo para reusar lógica dentro de un script. Usar CTE o repetir inline. Las `fn_`/`sp_` permanentes siguen la convención versionada (`_v2`, `_v3`).
+
+### Esquema siempre explícito
+
+```sql
+-- Correcto:
+SELECT * FROM esq_credito.tb_credito;
+
+-- Incorrecto:
+SELECT * FROM public.tb_credito;
+SELECT * FROM tb_credito;  -- sin schema
+```
+
+### Portabilidad
+
+PostgreSQL es el motor primario. Si el destino es otro motor, indicarlo en `Objeto:` o como nota libre debajo del header (no como campo nuevo). Ver `sql-rollback-generator/references/rollback-patterns.md` para equivalencias Oracle/SQL Server.
+
+### Seguridad en SQL dinámico
+
+Nunca concatenar strings en SQL dinámico. Usar `$1`/`$2` en queries parametrizados, o `%L` con `format()` en PL/pgSQL.
+
+---
+
+Para organización de scripts en sesiones de desarrollo: ver skill `sql-script-organizer`.
+Para rollback de scripts: ver skill `sql-rollback-generator`.
+
+## Scripts SQL
+
+Modificaciones a BD solo mediante scripts SQL versionados en el proyecto. Nunca ejecutar INSERT/UPDATE/DELETE/DDL directamente contra la BD.