refactor: standardize code style and formatting across codebase while introducing project integrity agent rules.

Author: joaltoroc

.agents/AGENTS.md

@@ -2,10 +2,19 @@
 
 This file documents workspace-specific rules, patterns, and guidelines that all AI coding assistants must adhere to when working on this repository.
 
-## MCP Tools & Discovery
+## Specialized Agents & Automated Scanners
 
-- **Codebase Memory**: This project uses `codebase-memory-mcp`. Always prefer using MCP graph tools (`search_graph`, `trace_path`, `get_code_snippet`, etc.) over raw grep/find commands for exploring the codebase.
-- **Mandatory Re-indexation**: After completing any task that creates, modifies, or deletes source files, you MUST re-index the repository by calling `index_repository` via `codebase-memory-mcp`. This keeps the knowledge graph in sync with the current codebase and ensures future graph queries remain accurate. Do this as the last step of every task before reporting completion.
+This project uses a dedicated ecosystem of specialized agents located in `.agents/skills/` and `.agents/rules/`:
+
+1. **Cybersecurity Agent (`cybersecurity-agent`)**: OWASP Top 10 auditing, secret leak prevention, SVG/XSS sanitization, SSRF protection, database query safety, and dependency vulnerability checks (`pnpm security:scan`).
+2. **Code Integrity Agent (`code-integrity-agent`)**: ESLint compliance, Prettier code formatting, dead code sweeping, DRY principles, and strict TypeScript checks (`pnpm integrity:scan`).
+3. **Architecture Agent (`architecture-agent`)**: Clean Architecture layer boundaries (Domain -> Use Cases -> Adapters -> Modules), monorepo package version synchronization, and documentation integrity (`pnpm architecture:scan`).
+4. **Best Practices Agent (`best-practices-agent`)**: Guard clauses (negation first), `readonly` class properties, runtime parameter type validation, exact package versions, and non-root Docker execution (`pnpm best-practices:scan`).
+
+To run the complete suite of agent checks before completing any task, run:
+```bash
+pnpm scan:all
+```
 
 ## Security Rules & Mandatory OWASP Review Workflow
 

.agents/rules/architecture-agent.md

@@ -0,0 +1,16 @@
+# Directivas del Agente de Arquitectura
+
+Este archivo define las reglas obligatorias de estructura y arquitectura Clean para todo agente o desarrollador en **GitCard Studio**.
+
+## 1. Escaneo Obligatorio Pre-Commit
+Antes de finalizar cualquier tarea que altere la estructura de carpetas, dependencias o módulos en el backend o frontend, se DEBE ejecutar:
+
+```bash
+pnpm architecture:scan
+```
+
+## 2. Reglas Estrictas de Arquitectura
+1. **Aislamiento de la Capa Domain**: `backend/src/domain` no debe importar módulos de `infrastructure`, `adapters`, `modules` ni librerías de infraestructura externa (Fastify, NestJS, TypeORM).
+2. **Desacoplamiento de Casos de Uso**: Los casos de uso (`use-cases/`) deben depender exclusivamente de interfaces de repositorio e interactuar con entidades de dominio.
+3. **Sincronización de Versiones Monorepo**: La propiedad `"version"` debe coincidir exactamente en `package.json`, `backend/package.json` y `frontend/package.json`.
+4. **Sincronización de Documentación**: Toda modificación arquitectónica o de despliegue requiere actualizar `README.md`, `CHANGELOG.md` y `.agents/ARCHITECTURE.md`.

.agents/rules/best-practices-agent.md

@@ -0,0 +1,17 @@
+# Directivas del Agente de Buenas Prácticas
+
+Este archivo define las reglas obligatorias de patrones de desarrollo y programación defensiva en **GitCard Studio**.
+
+## 1. Escaneo Obligatorio Pre-Commit
+Antes de dar por completada cualquier tarea, se DEBE ejecutar el análisis de buenas prácticas:
+
+```bash
+pnpm best-practices:scan
+```
+
+## 2. Reglas Estrictas de Patrones
+1. **Programación Defensiva y Cláusulas de Guardia**: Tratar primero la condición de falla/negación en cláusulas `if` (`if (!param) { return ...; }`) para evitar anidamiento.
+2. **Propiedades Inmutables (`readonly`)**: Marcar todas las dependencias inyectadas en constructores y propiedades de clase como `readonly`.
+3. **Validación de Parámetros de Consulta**: Verificar explícitamente el tipo `typeof req.query.x === 'string'` antes de utilizar parámetros HTTP.
+4. **Gestión de Paquetes y Versiones**: Usar exclusivamente `pnpm`. No instalar paquetes con prefijos `^` o `~` en `package.json`.
+5. **Aislamiento en Docker**: Garantizar que el contenedor ejecute la app bajo `USER node`.

.agents/rules/code-integrity-agent.md

@@ -0,0 +1,17 @@
+# Directivas del Agente de Integridad de Código
+
+Este archivo define las reglas obligatorias de calidad de código y formato para todo agente o desarrollador que modifique **GitCard Studio**.
+
+## 1. Escaneo Obligatorio Pre-Commit
+Antes de finalizar cualquier tarea que altere código fuente en backend o frontend, se DEBE ejecutar la verificación de integridad:
+
+```bash
+pnpm integrity:scan
+```
+
+## 2. Reglas Estrictas de Integridad y Limpieza
+1. **Formato Prettier**: Ningún archivo con código desalineado o sin formato debe ser enviado al repositorio. Usar `pnpm format`.
+2. **ESLint Sin Incidencias**: El comando `pnpm lint` debe arrojar `0` errores y `0` advertencias.
+3. **Limpieza de Código Muerto**: Prohibido dejar bloques de código fuente comentados (`// const x = ...`), importaciones no utilizadas o variables inactivas.
+4. **Principios DRY**: Reutilizar siempre helpers centralizados (como `renderBrandHeader` en presentadores SVG o `escapeXml` en sanitización) en lugar de duplicar lógica.
+5. **Tipado TypeScript Inmutable**: Utilizar `readonly` en miembros de clase privados o propiedades inicializadas que no se reasignan.

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 Todos los cambios notables en este proyecto serán documentados en este archivo.
 
+## [1.8.3] - 2026-08-24
+
+### 🤖 Ecosistema de Agentes Especializados & Auditoría Automatizada (`pnpm scan:all`)
+- **Sistema de Agentes Dedicados**: Creación e integración de 4 agentes especializados para garantizar la calidad del repositorio:
+  - **`cybersecurity-agent`**: Auditorías OWASP Top 10, sanitización XSS/SVG, prevención de SSRF/Inyección SQL y control de credenciales (`pnpm security:scan`).
+  - **`code-integrity-agent`**: Cumplimiento estricto de ESLint, Prettier, detección de código muerto y tipado inmutable (`pnpm integrity:scan`).
+  - **`architecture-agent`**: Verificación de límites de capa Clean Architecture, aislamiento del dominio y sincronización de documentación/versiones (`pnpm architecture:scan`).
+  - **`best-practices-agent`**: Programación defensiva con cláusulas de guardia (negación primero), modificadores `readonly` y versiones fijas exactas (`pnpm best-practices:scan`).
+- **Comando Unificado de Escaneo**: Añadido `pnpm scan:all` para ejecutar de forma consecutiva la suite completa de agentes antes de cada commit.
+
+### 📦 Gestor de Paquetes & Actualizaciones de Dependencias
+- **Sincronización de pnpm**: Actualizado el gestor de paquetes a `pnpm@11.24.0` en el `Dockerfile` (etapas builder y runner) y alineado con `packageManager` en `package.json`.
+- **Remediación de Seguridad en Dependencias (`pnpm audit`)**: Actualizado la anulación de `brace-expansion` a `5.0.9` en `pnpm-workspace.yaml`, logrando 0 vulnerabilidades reportadas.
+- **Actualización de Dependencias Frontend**: Actualizado `astro` a `7.2.5` y `happy-dom` a `20.11.6` en `frontend/package.json`.
+
 ## [1.8.2] - 2026-08-19
 
 ### 🛡️ Agente de Ciberseguridad & Auditorías de Seguridad Automatizadas
@@ -407,4 +422,4 @@ Todos los cambios notables en este proyecto serán documentados en este archivo.
 
 ---
 
-**Versión actualmente expuesta / en producción:** v1.8.2
+**Versión actualmente expuesta / en producción:** v1.8.3

Dockerfile

@@ -2,7 +2,7 @@
 FROM node:24-alpine AS builder
 
 # Install pnpm globally
-RUN npm install -g pnpm@11.20.0 --ignore-scripts
+RUN npm install -g pnpm@11.24.0 --ignore-scripts
 
 WORKDIR /usr/src/app
 
@@ -27,7 +27,7 @@ RUN pnpm run build
 FROM node:24-alpine AS runner
 
 # Install pnpm
-RUN npm install -g pnpm@11.20.0 --ignore-scripts
+RUN npm install -g pnpm@11.24.0 --ignore-scripts
 
 WORKDIR /usr/src/app
 

backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitcard-studio-backend",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "description": "High-performance NestJS & Fastify API backend server for GitCard Studio SVG stats card generation, OAuth integration, and metrics tracking.",
   "main": "dist/server.js",
   "scripts": {

backend/src/adapters/presenters/topReposCard.ts

@@ -24,7 +24,8 @@ export function renderTopReposCard(
   const repoRows = top4
     .map((repo, i) => {
       const y = HEADER_HEIGHT + i * ROW_HEIGHT;
-      const desc = repo.description.length > 55 ? `${repo.description.slice(0, 52)}…` : repo.description;
+      const desc =
+        repo.description.length > 55 ? `${repo.description.slice(0, 52)}…` : repo.description;
 
       return `
       <g transform="translate(0, ${y})">

backend/src/adapters/presenters/viewsBadge.ts

@@ -35,7 +35,6 @@ function resolveColor(colorParam?: string, themeParam?: string): string {
   return theme.accent;
 }
 
-
 export function renderViewsBadge(
   count: number,
   label?: string,

backend/src/adapters/repositories/ApiGitHubRepository.ts

@@ -165,7 +165,8 @@ export class ApiGitHubRepository implements IGitHubRepository {
     if (!reposData) {
       return { totalPublicCount: currentPublicCount, hasNextPage: false, afterCursor: null };
     }
-    const totalPublicCount = currentPublicCount === 0 ? (reposData.totalCount || 0) : currentPublicCount;
+    const totalPublicCount =
+      currentPublicCount === 0 ? reposData.totalCount || 0 : currentPublicCount;
     allRepoNodes.push(...(reposData.nodes ?? []));
     return {
       totalPublicCount,
@@ -194,11 +195,10 @@ export class ApiGitHubRepository implements IGitHubRepository {
         ? { after: afterCursor }
         : { username, after: afterCursor };
 
-      const data: { user?: any; viewer?: any } | null = await this.fetchGraphQL<{ user?: any; viewer?: any }>(
-        query,
-        variables,
-        userToken
-      );
+      const data: { user?: any; viewer?: any } | null = await this.fetchGraphQL<{
+        user?: any;
+        viewer?: any;
+      }>(query, variables, userToken);
 
       const currentUser: any = isViewer ? data?.viewer : data?.user;
       if (!currentUser) break;
@@ -1084,7 +1084,8 @@ export class ApiGitHubRepository implements IGitHubRepository {
       if (!sponsorEntity) continue;
 
       const tier = node.tier;
-      const dollars = tier?.monthlyPriceInDollars ?? Math.round((tier?.monthlyPriceInCents ?? 0) / 100);
+      const dollars =
+        tier?.monthlyPriceInDollars ?? Math.round((tier?.monthlyPriceInCents ?? 0) / 100);
       const isOneTime = Boolean(tier?.isOneTime);
 
       if (isOneTime) {
@@ -1223,7 +1224,10 @@ export class ApiGitHubRepository implements IGitHubRepository {
         }
       }
     } catch (err) {
-      logger.warn(`Could not fetch commit activity for user ${username}:`, { username, error: err });
+      logger.warn(`Could not fetch commit activity for user ${username}:`, {
+        username,
+        error: err
+      });
     }
 
     return {