@saulwade/swl-ses 1.0.0

package/habilidades/build-errors-typescript/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: build-errors-typescript
+description: >
+  Resolución de errores de compilación TypeScript: tsc, tsconfig.json, errores de
+  tipos, generics, declaration files y bundlers (Vite, esbuild, webpack). Cargar
+  cuando un build TypeScript falle, tsc reporte errores de tipos, o haya problemas
+  con la configuración del compilador o del bundler.
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash, Grep]
+exclusiones:
+  - "No cargar para errores de lógica o comportamiento en runtime JavaScript — si el código compila pero falla en ejecución (undefined is not a function, Promise sin await), no es un error de compilación TypeScript."
+  - "No cargar para errores específicos de frameworks sobre TypeScript (Angular TS2xxx en templates, NestJS decorators) — esos tienen contexto adicional de framework; cargar `angular-moderno`, `nestjs-experto` o `build-errors-nextjs`."
+  - "No cargar para decidir la configuración óptima de tsconfig desde cero en un proyecto nuevo — eso es diseño de stack; cargar `typescript-avanzado` para configuración y patrones generales."
+  - "No cargar cuando el error es de ESLint o Prettier (no de tsc) — los errores de style/lint no son errores de compilación TypeScript."
+evolvable: true  # default para skill estandar
+---
+# Build Errors TypeScript — Diagnóstico y Solución
+
+## Cuándo NO cargar
+
+- El error ocurre en runtime JavaScript (no en `tsc`) — si el build pasa pero el navegador/Node lanza errores, no es un problema de TypeScript.
+- El error viene de un framework encima de TypeScript (Angular, NestJS) — cargar el skill específico del framework porque el error puede tener semántica adicional.
+- La pregunta es cómo configurar tsconfig para un proyecto nuevo — para diseño de configuración cargar `typescript-avanzado`.
+
+## Cuándo cargar
+
+- `tsc` falla con errores de tipos, generics o declaration files
+- `npm run build` o `yarn build` falla en la etapa de type-checking
+- Errores de `tsconfig.json` (paths, module resolution, strict mode)
+- Problemas con `@types/*` (conflictos, tipos faltantes, versiones incompatibles)
+- Errores de bundlers (Vite, esbuild, webpack) relacionados con TypeScript
+- Errores de ESM vs CommonJS en proyectos TypeScript
+
+---
+
+## Errores de tsc — tipos y asignación
+
+### `TS2322: Type 'X' is not assignable to type 'Y'`
+
+**Causa**: asignación de un valor cuyo tipo no coincide con el esperado.
+
+```typescript
+// MAL
+const edad: number = "25";  // string no es number
+
+// BIEN — verificar el tipo real del valor
+const edad: number = parseInt("25", 10);
+
+// Caso frecuente: respuestas de API
+interface Usuario { id: number; nombre: string }
+// La API puede devolver id como string — validar en runtime
+const usuario: Usuario = await api.get("/users/1"); // puede fallar si id viene como "1"
+```
+
+**Gotcha con unions y narrowing**:
+```typescript
+// MAL — TS no sabe cuál es el tipo dentro de la union
+function procesar(valor: string | number) {
+  return valor.toFixed(2);  // TS2339: toFixed no existe en string
+}
+
+// BIEN — narrowing con typeof
+function procesar(valor: string | number) {
+  if (typeof valor === "number") {
+    return valor.toFixed(2);
+  }
+  return parseFloat(valor).toFixed(2);
+}
+```
+
+### `TS2345: Argument of type 'X' is not assignable to parameter of type 'Y'`
+
+**Causa frecuente**: pasar `null` o `undefined` donde se espera un tipo definido.
+
+```typescript
+// MAL — strictNullChecks detecta que find() puede retornar undefined
+const usuarios: Usuario[] = [];
+const admin: Usuario = usuarios.find(u => u.rol === "admin");
+// TS2322: Type 'Usuario | undefined' is not assignable to type 'Usuario'
+
+// BIEN — manejar el caso undefined
+const admin = usuarios.find(u => u.rol === "admin");
+if (!admin) throw new Error("Admin no encontrado");
+// Después de la guarda, TS sabe que admin es Usuario
+```
+
+### `TS2339: Property 'X' does not exist on type 'Y'`
+
+**Causas comunes**:
+1. Typo en el nombre de la propiedad
+2. El tipo no tiene esa propiedad (usar `interface` correcta)
+3. Acceso a propiedad opcional sin optional chaining
+
+```typescript
+// MAL
+const nombre = usuario.nombe;  // typo: "nombe" vs "nombre"
+
+// Caso con tipos de API externa
+const data: unknown = await fetch("/api").then(r => r.json());
+console.log(data.nombre);  // TS2339: unknown no tiene propiedades
+
+// BIEN — validar con type guard o Zod
+import { z } from "zod";
+const UsuarioSchema = z.object({ nombre: z.string() });
+const usuario = UsuarioSchema.parse(data);
+console.log(usuario.nombre);  // ok: tipo inferido por Zod
+```
+
+---
+
+## Errores de tsconfig.json
+
+### `Cannot find module 'X' or its corresponding type declarations` (TS2307)
+
+**Diagnóstico**:
+```bash
+# ¿Existe el paquete?
+npm ls nombre-paquete
+
+# ¿Existen los tipos?
+npm ls @types/nombre-paquete
+
+# ¿moduleResolution es correcto?
+grep moduleResolution tsconfig.json
+```
+
+**Soluciones**:
+1. Instalar tipos: `npm install -D @types/nombre-paquete`
+2. Si no hay `@types/*`, crear declaración local:
+   ```typescript
+   // src/types/nombre-paquete.d.ts
+   declare module "nombre-paquete" {
+     export function metodo(): void;
+   }
+   ```
+3. Verificar `moduleResolution` en tsconfig:
+   ```json
+   {
+     "compilerOptions": {
+       "moduleResolution": "bundler"  // para Vite/esbuild
+       // o "node16" para Node.js puro
+       // NUNCA "node" en proyectos nuevos (legacy)
+     }
+   }
+   ```
+
+### Path aliases no resuelven (`@app/`, `@shared/`)
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@app/*": ["src/app/*"],
+      "@shared/*": ["src/shared/*"]
+    }
+  }
+}
+```
+
+**Gotcha**: `tsc` resuelve los paths pero NO los transforma en el output.
+El bundler (Vite, webpack) o `tsc-alias` deben resolver los paths en runtime.
+
+```bash
+# Para Vite — agregar resolve.alias en vite.config.ts
+# Para Jest — agregar moduleNameMapper en jest.config.ts
+# Para Node.js — usar tsc-alias como post-build step
+npx tsc && npx tsc-alias
+```
+
+### `TS5023: Unknown compiler option 'X'`
+
+**Causa**: opción de una versión más nueva de TypeScript en tsconfig.
+
+```bash
+# Verificar versión de TypeScript
+npx tsc --version
+
+# Opciones por versión:
+# verbatimModuleSyntax — TS 5.0+
+# moduleResolution: "bundler" — TS 5.0+
+# resolvePackageJsonExports — TS 5.0+
+```
+
+**Solución**: actualizar TypeScript o quitar la opción incompatible.
+
+---
+
+## Errores de generics
+
+### `TS2344: Type 'X' does not satisfy the constraint 'Y'`
+
+```typescript
+// MAL — el generic está restringido pero el tipo pasado no cumple
+function primero<T extends { id: number }>(items: T[]): T {
+  return items[0];
+}
+primero([{ nombre: "Ana" }]);  // error: falta 'id'
+
+// BIEN
+primero([{ id: 1, nombre: "Ana" }]);
+```
+
+### `TS2558: Expected 0 type arguments, but got 1`
+
+**Causa**: pasar generics a una función que no los acepta.
+
+```typescript
+// MAL — useState ya infiere el tipo del valor inicial
+const [count, setCount] = useState<number>(0);  // redundante pero válido
+
+// Esto falla si la función no tiene parámetro de tipo:
+fetch<Response>("/api");  // TS2558: fetch no acepta type arguments
+```
+
+---
+
+## Errores de ESM vs CommonJS
+
+### `ERR_REQUIRE_ESM: require() of ES Module not supported`
+
+**Causa**: importar un paquete ESM-only desde un proyecto CommonJS.
+
+```bash
+# Diagnóstico: ver si el paquete es ESM-only
+node -e "console.log(require.resolve('nombre-paquete'))"
+# Si falla con ERR_REQUIRE_ESM, el paquete es ESM-only
+```
+
+**Soluciones**:
+1. Migrar el proyecto a ESM (`"type": "module"` en package.json)
+2. Usar `import()` dinámico en vez de `require()`:
+   ```typescript
+   const modulo = await import("paquete-esm");
+   ```
+3. Usar una versión anterior del paquete que soporte CJS (último recurso)
+
+### `TS1479: ... resolves to an ESM-only module` con `moduleResolution: "node16"`
+
+```json
+{
+  "compilerOptions": {
+    "module": "node16",
+    "moduleResolution": "node16"
+  }
+}
+```
+
+**Solución**: cambiar a `"moduleResolution": "bundler"` si usas Vite/esbuild,
+o usar `import()` dinámico para paquetes ESM-only.
+
+---
+
+## Errores de bundlers (Vite, esbuild, webpack)
+
+### Vite: `[plugin:vite:import-analysis] Failed to resolve import`
+
+**Causas**:
+1. Path alias no configurado en `vite.config.ts`
+2. Extensión faltante en el import (Vite requiere extensión para CSS/assets)
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import { resolve } from "path";
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      "@": resolve(__dirname, "./src"),
+    },
+  },
+});
+```
+
+### webpack: `Module not found: Error: Can't resolve 'X'`
+
+```bash
+# Diagnóstico
+npx webpack --stats-error-details
+
+# Soluciones comunes:
+# 1. Agregar extensión a resolve.extensions en webpack.config
+# 2. Agregar alias a resolve.alias
+# 3. Instalar el loader correspondiente (ts-loader, babel-loader)
+```
+
+### esbuild: `No loader is configured for ".X" files`
+
+```typescript
+// esbuild necesita loaders explícitos para extensiones no estándar
+import * as esbuild from "esbuild";
+await esbuild.build({
+  loader: {
+    ".svg": "file",
+    ".css": "css",
+    ".png": "file",
+  },
+});
+```
+
+---
+
+## Errores de declaration files (.d.ts)
+
+### `TS7016: Could not find a declaration file for module 'X'`
+
+```bash
+# Opción 1: instalar tipos del DefinitelyTyped
+npm install -D @types/nombre-paquete
+
+# Opción 2: declaración local mínima
+# src/types/nombre-paquete.d.ts
+declare module "nombre-paquete";  # tipado como any — último recurso
+
+# Opción 3: skipLibCheck (oculta errores, no los resuelve)
+# tsconfig.json → "skipLibCheck": true
+```
+
+### Conflictos entre versiones de `@types/*`
+
+```bash
+# Diagnóstico
+npm ls @types/react  # ver si hay múltiples versiones
+
+# Solución: forzar una sola versión con overrides
+# package.json
+{
+  "overrides": {
+    "@types/react": "^18.2.0"
+  }
+}
+```
+
+---
+
+## strict mode — errores al activar
+
+Al migrar un proyecto a `"strict": true`, los errores más comunes:
+
+| Error | Flag específico | Solución rápida |
+|-------|----------------|-----------------|
+| `TS7006: Parameter implicitly has 'any'` | `noImplicitAny` | Agregar tipo al parámetro |
+| `TS2532: Object is possibly 'undefined'` | `strictNullChecks` | Optional chaining `?.` o guarda `if` |
+| `TS2564: Property has no initializer` | `strictPropertyInitialization` | Inicializar o marcar con `!` (non-null assertion) |
+| `TS7053: Element implicitly has 'any'` | `noImplicitAny` | Usar `Record<string, T>` o index signature |
+
+**Estrategia de migración incremental**: activar flags uno a uno en vez de `strict: true`
+de golpe. Empezar con `noImplicitAny`, luego `strictNullChecks`, luego el resto.
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **`tsc --noEmit` pasa localmente pero CI falla con TS2307 en el mismo archivo**: la versión de TypeScript en node_modules local difiere de la versión en CI. Causa: `typescript` está en `devDependencies` con rango `^5.0.0` y npm resolvió versiones distintas en los dos entornos. Solución: fijar la versión exacta en devDependencies (`"typescript": "5.3.3"` sin `^`) o usar `npm ci` con lockfile en CI.
+- **Path alias `@app/*` resuelve en `tsc` pero falla en Jest con `Cannot find module '@app/...'`**: `tsc` maneja los aliases del tsconfig pero el runner de Jest no los conoce por defecto. Causa: Jest no lee `tsconfig.json` para resolución de módulos; necesita `moduleNameMapper` equivalente en `jest.config.ts`. Solución: agregar `moduleNameMapper: {"^@app/(.*)$": "<rootDir>/src/app/$1"}` al jest config, idéntico al paths del tsconfig.
+- **`skipLibCheck: true` oculta errores que rompen el build en el servidor de CI del cliente**: el desarrollador activó `skipLibCheck` para silenciar errores de `@types/*` conflictivos sin resolver el conflicto real. Causa: múltiples versiones del mismo `@types/` paquete en el árbol de dependencias. Solución: usar `npm ls @types/react` para detectar duplicados y resolver con `overrides` en package.json — `skipLibCheck` debe ser temporal, no permanente.
+- **`TS1259: Module can only be default-imported using 'esModuleInterop'`**: importar un módulo CommonJS con `import X from 'x'` cuando `esModuleInterop: false`. Causa: ausencia de `"esModuleInterop": true` en tsconfig. El gotcha es que activarlo solo resuelve el error de tsc pero no garantiza que el bundler produzca el import correcto. Solución: activar `esModuleInterop: true` junto con `allowSyntheticDefaultImports: true` y verificar que el bundler también tiene su equivalente configurado.
+
+## Checklist de diagnóstico
+
+- [ ] `npx tsc --version` — ¿versión compatible con las opciones de tsconfig?
+- [ ] `npx tsc --noEmit` — ¿type-check pasa sin emitir?
+- [ ] ¿`moduleResolution` es `bundler` (Vite/esbuild) o `node16` (Node.js)?
+- [ ] ¿Los `@types/*` están instalados para paquetes sin tipos propios?
+- [ ] ¿Path aliases configurados en tsconfig Y en el bundler/runner?
+- [ ] ¿El proyecto es ESM (`"type": "module"`) o CJS? ¿Consistente con tsconfig?
+- [ ] `npm ls --all | grep "deduped"` — ¿conflictos de versiones de tipos?
+- [ ] Para errores de strict: ¿el flag específico que causa el error está identificado?

package/habilidades/checklist-calidad/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: checklist-calidad
+description: Evaluación de calidad del trabajo entregado con 7 métricas ponderadas — bugs encontrados, cobertura de tests, conformidad con spec, alucinaciones de código, DRY, seguridad SIGAF y arquitectura. Score ponderado mínimo de 9.0 sobre 10 para aprobar. Produce un reporte con score y plan de mejora.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para revisión de seguridad en profundidad (OWASP, CVEs, vulnerabilidades) — para seguridad cargar `checklist-seguridad`."
+  - "No cargar para auditoría de dependencias (licencias, CVEs en paquetes) — para dependencias cargar `dependencias-auditoria`."
+  - "No cargar para revisión de código por lenguaje específico (Python, TypeScript, SQL) — para revisión por stack cargar el skill del lenguaje correspondiente."
+  - "No cargar durante la implementación — se activa AL TERMINAR una fase, no durante el desarrollo."
+---
+# Habilidad: Checklist de Calidad del Trabajo
+
+## Cuándo NO cargar
+
+- La revisión es de seguridad (OWASP, inyección, auth): cargar `checklist-seguridad`.
+- La auditoría es de dependencias (CVEs en paquetes, licencias): cargar `dependencias-auditoria`.
+- La revisión es de código fuente por stack específico: cargar el skill del lenguaje (`patrones-python`, `angular-moderno`, etc.).
+- Se está en medio de la implementación: este skill se activa al terminar una fase, no durante el desarrollo.
+
+## Propósito
+
+La calidad no es subjetiva — es medible. Esta habilidad aplica 7 métricas
+concretas al trabajo entregado y produce un score numérico. Un score menor
+a 9.0 bloquea el avance a producción y requiere un plan de mejora explícito.
+
+## Cuándo activar
+
+- Al terminar una fase antes de marcar como "completada"
+- Como parte del proceso de revisión de PRs críticos
+- Cuando el usuario pide evaluación de calidad del trabajo
+- Después de correcciones del verificador para re-evaluar
+
+---
+
+## Métrica 1 — Bugs Encontrados (peso: 25%)
+
+**Definición**: Número de defectos funcionales encontrados durante la verificación.
+
+**Cómo medir**:
+1. Ejecutar todos los tests: `pytest -v` / `npm test`
+2. Ejecutar el tipo-checker: `mypy .` / `tsc --noEmit`
+3. Ejecutar el linter: `ruff check .` / `eslint .`
+4. Revisión manual de flujos críticos (happy path + edge cases)
+
+**Escala de puntuación**:
+| Bugs encontrados | Puntuación |
+|-----------------|-----------|
+| 0 bugs | 10.0 |
+| 1-2 bugs menores | 8.5 |
+| 3-5 bugs menores | 7.0 |
+| 1 bug mayor | 5.0 |
+| 2+ bugs mayores | 0.0 |
+
+**Bug menor**: no bloquea flujo principal, workaround disponible.
+**Bug mayor**: bloquea flujo principal o corrompe datos.
+
+---
+
+## Métrica 2 — Cobertura de Tests (peso: 20%)
+
+**Definición**: Porcentaje de líneas/branches cubiertos por tests automáticos.
+
+**Cómo medir**:
+```bash
+# Python
+pytest --cov=. --cov-report=term-missing --cov-report=html
+
+# TypeScript/Angular
+npx jest --coverage
+```
+
+**Escala de puntuación**:
+| Cobertura | Puntuación |
+|-----------|-----------|
+| ≥90% | 10.0 |
+| 80-89% | 8.5 |
+| 70-79% | 7.0 |
+| 60-69% | 5.0 |
+| <60% | 3.0 |
+| Sin tests | 0.0 |
+
+**Nota**: La cobertura de líneas es necesaria pero no suficiente. Verificar
+también que los tests tienen assertions reales (ver habilidad `verificar-trabajo`
+nivel SUSTANTIVO para tests).
+
+---
+
+## Métrica 3 — Conformidad con Spec (peso: 20%)
+
+**Definición**: Porcentaje de requerimientos del PLAN.md / CONTEXT.md implementados
+correctamente.
+
+**Cómo medir**:
+1. Listar todos los criterios de aceptación del CONTEXT.md
+2. Para cada uno, verificar si está implementado (PASS/FAIL)
+3. Score = (criterios PASS / total criterios) * 10
+
+**Puntos de penalización adicional**:
+- -1.0: Feature implementada de forma diferente a la spec sin notificación
+- -0.5: Feature parcialmente implementada sin documentar qué falta
+- -1.5: Feature de seguridad omitida (RBAC, validación, etc.)
+
+---
+
+## Métrica 4 — Alucinaciones de Código (peso: 15%)
+
+**Definición**: Código que parece correcto pero introduce lógica incorrecta,
+usa APIs inexistentes o hace suposiciones falsas sobre el sistema.
+
+**Señales a buscar**:
+- [ ] Imports de módulos que no existen en el proyecto
+- [ ] Llamadas a métodos con firmas incorrectas
+- [ ] Variables de entorno asumidas que no están en `.env.example`
+- [ ] Endpoints referenciados que no existen en el router
+- [ ] Lógica de negocio que contradice los requerimientos documentados
+- [ ] Valores hardcodeados que deberían venir de configuración
+- [ ] Schemas Pydantic con campos que no existen en el modelo ORM
+
+**Cómo detectar**:
+```bash
+# Importaciones que no resuelven
+mypy . 2>&1 | grep "Cannot find\|Module.*has no attribute"
+
+# Variables de entorno sin documentar
+grep -rn "os\.getenv\|os\.environ" --include="*.py" | \
+  awk '{print $2}' | sort | uniq > env_usados.txt
+grep -rn "^[A-Z_]*=" .env.example | awk -F= '{print $1}' | sort > env_documentados.txt
+diff env_usados.txt env_documentados.txt
+```
+
+**Escala de puntuación**:
+| Alucinaciones | Puntuación |
+|--------------|-----------|
+| 0 | 10.0 |
+| 1-2 menores (import inexistente, typo) | 7.0 |
+| 1 mayor (lógica incorrecta) | 4.0 |
+| 2+ mayores | 0.0 |
+
+---
+
+## Métrica 5 — Principio DRY (peso: 10%)
+
+**Definición**: No repetición innecesaria de lógica o código.
+
+**Cómo medir** — buscar duplicación:
+```bash
+# Funciones similares (Python)
+# Herramienta: pylint, sonarqube o revisión manual
+grep -rn "def " --include="*.py" | awk -F: '{print $3}' | sort | uniq -d | head -20
+
+# Bloques de código > 10 líneas idénticos
+# Revisión manual de services y utils
+```
+
+**Items a verificar**:
+- [ ] Sin funciones duplicadas entre módulos
+- [ ] Sin queries SQL duplicadas que deberían ser un helper
+- [ ] Sin lógica de validación repetida que debería estar en un validator
+- [ ] Sin constantes definidas en múltiples lugares
+- [ ] Sin componentes Angular que hacen lo mismo con diferente nombre
+
+**Escala**:
+| DRY violations | Puntuación |
+|---------------|-----------|
+| 0 | 10.0 |
+| 1-2 menores | 8.0 |
+| 3-5 | 6.0 |
+| 5+ o duplicación de lógica crítica | 3.0 |
+
+---
+
+## Métrica 6 — Seguridad SIGAF (peso: 5%)
+
+**Definición**: Cumplimiento de las reglas anti-error SIGAF documentadas en el
+sistema. Esta métrica es binaria por categoría.
+
+**Checklist SIGAF**:
+- [ ] selectinload en todas las relaciones accedidas en serialización
+- [ ] lazy="selectin" en relaciones a Usuario
+- [ ] Services no hacen db.commit()
+- [ ] Literal[] en campos enum en schemas Pydantic
+- [ ] RBAC en todos los POST/PUT/DELETE
+- [ ] get_current_user explícito en todos los endpoints
+- [ ] Filtros de datos del JWT, no de query params
+- [ ] @if/@for en Angular (no *ngIf/*ngFor)
+- [ ] computed() para derivaciones en templates
+
+**Escala**:
+| Items fallidos | Puntuación |
+|---------------|-----------|
+| 0 | 10.0 |
+| 1 | 7.0 |
+| 2 | 4.0 |
+| 3+ | 0.0 |
+
+---
+
+## Métrica 7 — Arquitectura (peso: 5%)
+
+**Definición**: El código nuevo respeta las capas y convenciones del proyecto.
+
+**Items a verificar**:
+- [ ] Services no importan directamente modelos de otros dominios (bypassing capas)
+- [ ] Endpoints no tienen lógica de negocio incrustada (lógica en services)
+- [ ] Componentes Angular no hacen llamadas HTTP directamente (usan services)
+- [ ] Modelos ORM no tienen lógica de negocio compleja (en services)
+- [ ] No se introdujeron nuevas dependencias sin justificación documentada
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**La Métrica 2 (cobertura) pasa al 85% pero todos los tests son de happy path**: la cobertura de líneas no detecta que los tests omiten los casos de error, los inputs nulos y los edge cases. Causa: es más fácil alcanzar 80% cubriendo el flujo principal que cubriendo los branches de validación. Fix: complementar el porcentaje de cobertura con revisión manual de qué branches están sin cubrir — `pytest --cov-branch` reporta cobertura de branches, no solo de líneas. Un 80% de branch coverage es más significativo que un 90% de line coverage.
+
+**La Métrica 4 (alucinaciones) pasa porque `mypy` no detecta errores, pero hay lógica incorrecta**: `mypy` verifica tipos, no semántica de negocio. Un endpoint que siempre devuelve `200 OK` aunque la operación falle, o una función que suma precios en lugar de multiplicar, pasa todos los type checks. Causa: las alucinaciones semánticas son invisibles para el análisis estático. Fix: la Métrica 4 requiere revisión manual del flujo de negocio crítico, no solo ejecutar herramientas automáticas. Verificar que la lógica implementada coincide con los criterios de aceptación del PLAN.md.
+
+**El score final es 9.2 pero hay un item de seguridad SIGAF fallido con "penalización mínima"**: la Métrica 6 tiene peso solo del 5%, por lo que un RBAC faltante baja el score de 10 a 9.5 — por encima del umbral de 9.0. Causa: el sistema de pesos numéricos permite que un defecto de seguridad crítico quede diluido por buenas métricas en otras categorías. Fix: los ítems de la Métrica 6 son veto independiente del score: si algún ítem de RBAC, selectinload o get_current_user falla, el veredicto es RECHAZADO independientemente del score ponderado.
+
+**La Métrica 3 (conformidad con spec) puntúa 10/10 porque el implementador revisó su propia spec**: el agente que implementó el código también evalúa si cumple los criterios que él mismo escribió. Causa: la Métrica 3 requiere contrastar el código contra criterios externos, no autoevaluación. Fix: la conformidad con spec debe verificarse contra el PLAN.md aprobado, no contra la memoria del implementador. Leer el PLAN.md antes de puntuar la Métrica 3 y citar el número de criterio de aceptación que cada ítem satisface.
+
+## Cálculo del score final
+
+```
+Score = (M1 * 0.25) + (M2 * 0.20) + (M3 * 0.20) + (M4 * 0.15)
+      + (M5 * 0.10) + (M6 * 0.05) + (M7 * 0.05)
+```
+
+| Score | Veredicto |
+|-------|-----------|
+| 9.0 - 10.0 | APROBADO |
+| 7.0 - 8.9 | APROBADO CON OBSERVACIONES (debe mejorarse antes de siguiente fase) |
+| 5.0 - 6.9 | RECHAZADO — requiere trabajo de corrección |
+| < 5.0 | RECHAZADO CRÍTICO — requiere reescritura parcial |
+
+---
+
+## Plantilla de reporte: `QUALITY-REPORT.md`
+
+```markdown
+# QUALITY-REPORT.md — Fase [N]
+**Fecha**: [fecha]  **Evaluador**: [agente/persona]
+
+## Score Final: [X.X / 10.0] — [VEREDICTO]
+
+## Desglose de métricas
+| # | Métrica | Peso | Puntuación | Score ponderado |
+|---|---------|------|-----------|----------------|
+| 1 | Bugs encontrados | 25% | [X]/10 | [X*0.25] |
+| 2 | Cobertura de tests | 20% | [X]/10 | [X*0.20] |
+| 3 | Conformidad con spec | 20% | [X]/10 | [X*0.20] |
+| 4 | Alucinaciones | 15% | [X]/10 | [X*0.15] |
+| 5 | DRY | 10% | [X]/10 | [X*0.10] |
+| 6 | Seguridad SIGAF | 5% | [X]/10 | [X*0.05] |
+| 7 | Arquitectura | 5% | [X]/10 | [X*0.05] |
+| **TOTAL** | | **100%** | | **[SCORE]** |
+
+## Hallazgos por métrica
+[Para cada métrica con puntuación < 9.0, listar los hallazgos específicos]
+
+## Plan de mejora (si score < 9.0)
+| Acción | Impacto en score | Tiempo estimado | Prioridad |
+|--------|----------------|----------------|----------|
+|        |                |                |          |
+
+## Decisión
+[ ] Aprobar para siguiente fase
+[ ] Aprobar con compromisos de mejora
+[ ] Rechazar — requiere iteración
+```