Instruction file imported from gicupc/junior-doc-gen-tests-cursor (.cursor/rules/architect-brain.mdc). Copyright stays with the author.

PROTOCOLO DE AUTOGESTION INTELIGENTE, GUARDIA DE DOCUMENTACION Y SINCRONIZACION

REGLA INMEDIATA: Al iniciar, ejecuta ls -R para detectar el contexto.

Detecta uno de tres casos posibles:

1. /docs/ vacio o inexistente → activa On(project_start) automaticamente (CASO A).
2. /docs/ poblado pero TODOS los .md tienen <!-- TEMPLATE-PLACEHOLDER --> como primera linea → trata el proyecto como NUEVO (son templates del scaffolding sin rellenar). Procede como en el caso 1: arranca On(project_start) y sobrescribe los templates al rellenarlos.
3. /docs/ poblado y al menos un .md NO tiene el marcador → es un proyecto con trabajo previo. NO arranques /inicio automaticamente; ofrece el menu de CASO B (regularizar / evolucionar / reparar / regularizar+tests+BD+frontend).

El marcador <!-- TEMPLATE-PLACEHOLDER --> se elimina de cada archivo al rellenarlo con contenido real. Una vez eliminado, el archivo deja de considerarse template.

📌 FUENTE DE VERDAD (SSOT)

• Los archivos .md de /docs/ son la fuente de verdad del proyecto.
• La memoria auto-generada del IDE es solo un acelerador de contexto, NO es fuente de verdad.
• Si algo en la memoria auto-generada contradice un doc de /docs/, ganan los docs.
• Si detectas esta contradiccion, avisa al usuario antes de actuar.

🛑 INTERRUPCION DE SEGURIDAD (OBLIGATORIO)

Antes de modificar, anadir o reparar codigo, DEBES preguntar: "He recibido tu peticion. Segun el protocolo de calidad:

1. ¿Actualizo docs/user-stories.md y docs/roadmap.md primero?
2. ¿Hay nuevas reglas para docs/blueprints.md?
3. ¿Los tests asociados estan planificados en docs/testing-strategy.md?
4. ¿Esta peticion implica una decision no trivial que debo registrar en docs/decisions-log.md?
5. ¿Esta peticion toca la base de datos? Si es si, ¿debo actualizar docs/database-strategy.md?
6. ¿Esta peticion toca el frontend (componentes, paginas, estilos, a11y)? Si es si, ¿debo actualizar docs/frontend-strategy.md?
7. ¿Esta peticion implica criterios de aceptacion validables por stakeholders no tecnicos? Si es si, ¿procede adoptar o ampliar BDD (/bdd) y registrar la decision?
8. ¿Voy a usar agentes IA (Cursor Agent, Claude Code, Copilot, Playwright MCP) para generar o mantener tests? Si es si, recuerda la politica de trazabilidad: cada test generado con *.prompt.md asociado, code review obligatoria, y consideraciones GDPR / EU AI Act si la app es de alto riesgo.
9. ¿Esta peticion toca package.json, lockfile, .npmrc, pnpm-workspace.yaml o .github/workflows/? Si es si, ¿debo actualizar docs/supply-chain-strategy.md y verificar que las defensas siguen activas?

No tocare el codigo hasta que confirmes la sincronizacion documental."

🔒 CIERRE DE TAREA OBLIGATORIO (ANTIDRIFT)

Al terminar CUALQUIER tarea de codigo, ejecuta SIEMPRE el protocolo On(task_complete) definido en @prompts/architect-brain.md. El checklist de sincronizacion documental debe aparecer VISIBLE al final de cada tarea, con cada doc marcado como actualizado o como "sin cambios" con justificacion.

Una tarea NO esta cerrada si el checklist no se ha mostrado.

Si detectas que olvidaste actualizar un doc, NO cierres la tarea: pide permiso para anadir la actualizacion faltante antes de cerrar.

Verificacion anti-template-residual (v4.7.1): si la tarea creo o modifico algun archivo del SSOT en /docs/, antes de cerrar la tarea verifica que ningun archivo de /docs/*.md empiece con <!-- TEMPLATE-PLACEHOLDER -->. Equivalente a head -1 docs/*.md | grep -c "TEMPLATE-PLACEHOLDER" debe devolver 0. Si encuentras algun archivo con marcador residual, eliminalo silenciosamente antes de mostrar el checklist final. Esta verificacion es obligatoria porque un marcador residual hace que el sistema vuelva a tratar el proyecto como "template sin rellenar" en futuras ejecuciones de /inicio, perdiendo el trabajo previo.

CASO A: PROYECTO NUEVO

Si no hay codigo:

1. Carga @prompts/architect-brain.md.
2. Lanza la Entrevista BMADT (Beneficio, Mecanismo, Alcance, Datos, Testing).
3. Genera el pack en docs/: prd.md, architecture.md, roadmap.md, user-stories.md, testing-strategy.md, decisions-log.md.
4. Ejecuta el protocolo On(testing_setup) ANTES del primer ticket funcional: instala framework de tests + soporte de linter del framework, crea configuracion minima, verifica que un smoke test pasa.
5. Si la respuesta M (Mecanismo) o D (Datos) implica base de datos, ejecuta tambien On(database_setup) despues del testing_setup:
   • Carga @.cursor/skills/database-skill/SKILL.md.
   • Detecta motor + ORM apropiados.
   • Identifica campos PII y su tratamiento.
   • Genera docs/database-strategy.md.
   • Configura entorno (Testcontainers, pg_stat_statements, etc.).
   • Registra ADRs y tickets correspondientes.
6. Si la respuesta M (Mecanismo) implica frontend (React, Vue, Svelte, Next, Nuxt, Astro, etc.), ejecuta tambien On(frontend_setup) despues del database_setup (o despues del testing_setup si no hay BD):
   • Carga @.cursor/skills/frontend-skill/SKILL.md (y visual-testing-skill si nivel T es 2 o 3).
   • Propon stack canonico 2026: Next.js 15/16 + TypeScript estricto + Tailwind v4 + shadcn/ui + Biome + Zod.
   • Pregunta sobre flujo diseno-a-codigo (Figma con Dev Mode, capturas, sin diseno) y propon MCP servers a activar (descomentar bloques en .cursor/mcp.json: Figma Dev Mode MCP, shadcn MCP, Chrome DevTools MCP, Playwright MCP).
   • Configura cabeceras de seguridad (CSP, HSTS, X-Frame-Options, Referrer-Policy).
   • Genera docs/frontend-strategy.md.
   • Registra ADRs y tickets correspondientes (a11y WCAG 2.2 AA, CWV como DoD, RUM, i18n si aplica).
7. Si el proyecto usa npm registry (Node.js, JS/TS, cualquier stack con package.json), ejecuta tambien On(supply_chain_setup):
   • Carga @.cursor/skills/supply-chain-skill/SKILL.md.
   • Detecta package manager y aplica defensas Capa 1 (minimumReleaseAge) y Capa 2 (allowBuilds / ignore-scripts).
   • Audita workflows en .github/workflows/ si existen (NO pull_request_target con checkout del fork; acciones pineadas a SHA).
   • Genera docs/supply-chain-strategy.md.
   • Registra ADRs y tickets correspondientes.
8. Registra las decisiones iniciales (respuestas BMADT) en decisions-log.md.

CASO B: PROYECTO EXISTENTE

Si hay codigo pero no hay /docs/ completos:

1. Ofrece el menu:
   • [1] Regularizar (Escanear y crear blueprints).
   • [2] Evolucionar (Anadir funcionalidad).
   • [3] Reparar (Corregir errores puntuales).
   • [4] Regularizar + Cubrir con tests + auditar BD + auditar frontend (Blueprints + setup de tests + cobertura de logica critica + auditoria de BD si aplica + auditoria de frontend si aplica).
2. Tu prioridad por defecto es crear docs/blueprints.md analizando los patrones del codigo actual.
3. Si se elige [4]:
   • Detecta el stack leyendo composer.json, package.json, archivos fuente.
   • Identifica "logica critica" (validadores, servicios, reglas de negocio) ignorando fontaneria.
   • Carga @.cursor/skills/tests-skill/SKILL.md como guia general.
   • Carga ADICIONALMENTE @.cursor/skills/legacy-testing-skill/SKILL.md si detectas codigo legacy sospechoso o divergencias con contrato formal.
   • Instala dependencias (framework + soporte de linter), crea configuracion y genera tests priorizando la logica critica.
   • Distingue SPEC vs CHARACTERIZATION en los tests segun la skill de legacy.
   • Si el proyecto tiene base de datos, ejecuta tambien On(database_audit):
     • Carga @.cursor/skills/database-skill/SKILL.md.
     • Realiza las 4 auditorias (modelo, seguridad, rendimiento, calidad de datos).
     • Genera docs/database-audit.md y docs/investigacion_seguridad.md si hay hallazgos relevantes.
     • Genera docs/database-strategy.md documentando el estado actual.
     • Crea tickets en roadmap.md por hallazgos criticos y de severidad alta.
   • Si el proyecto tiene frontend, ejecuta tambien On(frontend_audit):
     • Carga @.cursor/skills/frontend-skill/SKILL.md.
     • Realiza las 4 auditorias (stack y mantenibilidad, seguridad, rendimiento CWV, accesibilidad WCAG 2.2 AA).
     • Genera docs/frontend-audit.md y comparte hallazgos de seguridad con docs/investigacion_seguridad.md.
     • Genera docs/frontend-strategy.md documentando el estado actual.
     • Crea tickets en roadmap.md por hallazgos criticos y de severidad alta.
   • Si el proyecto usa npm registry (package.json presente), ejecuta tambien On(supply_chain_audit):
     • Carga @.cursor/skills/supply-chain-skill/SKILL.md.
     • Audita las 4 capas: dependency resolution, install-time execution, CI execution (GitHub Actions), publish path (OIDC trusted publishing).
     • Cross-referencia el lockfile con bases publicas de paquetes comprometidos (TanStack, Shai-Hulud, axios, Trivy).
     • Genera docs/supply-chain-audit.md y comparte hallazgos criticos/altos con docs/investigacion_seguridad.md.
     • Genera docs/supply-chain-strategy.md documentando el estado actual.
     • Crea tickets en roadmap.md por hallazgos criticos y de severidad alta.
   • Documenta en docs/testing-strategy.md que se ha cubierto y que queda pendiente.
   • Registra decisiones en decisions-log.md.
   • Anade tickets al roadmap.md por cada zona NO cubierta.

COMANDOS DEL USUARIO (disparadores de skills)

Reconoce y ejecuta estos comandos cuando aparezcan en la conversacion:

TESTING (obligatorio en todo proyecto)

• Todo proyecto nuevo arranca con entorno de tests configurado ANTES del primer codigo funcional.
• Un ticket NO se marca [x] en roadmap.md hasta que sus tests esten en verde.
• Los tests viven en la carpeta convencional del stack — documentada en docs/testing-strategy.md.
• Piramide de tests del proyecto documentada en docs/testing-strategy.md con 5 niveles posibles:
  • Unit (obligatorio en logica critica) — @.cursor/skills/tests-skill/SKILL.md.
  • Integracion (recomendado si hay APIs o BD) — @.cursor/skills/integration-testing-skill/SKILL.md.
  • E2E + visual + a11y (recomendado si hay frontend) — @.cursor/skills/visual-testing-skill/SKILL.md.
  • BDD / Aceptacion (opcional, solo con Three Amigos) — @.cursor/skills/bdd-skill/SKILL.md.
  • Legacy / Characterization (condicional) — @.cursor/skills/legacy-testing-skill/SKILL.md.
• Logica critica (validadores, servicios, reglas de negocio, calculos) tiene tests obligatorios.
• UI trivial, getters/setters, renders simples y fontaneria quedan fuera del scope de tests UNITARIOS, pero los componentes con interaccion deben tener tests de COMPONENTE con axe.
• Las dependencias externas (BD, APIs, sistema de archivos) se mockean en tests unitarios.
• Si el proyecto tiene BD, los tests de integracion usan Testcontainers o equivalente.
• Si el proyecto tiene APIs HTTP, los tests de integracion usan Supertest + MSW (mocks reutilizables entre integration y E2E).
• Si el proyecto tiene frontend con nivel T 2 o 3, los componentes con interaccion tienen tests de componente con vitest-axe y los flujos criticos tienen tests E2E con @playwright/test + @axe-core/playwright.
• Recomendacion 2026: en proyectos NUEVOS JS/TS con Vite / Next.js 15+ / React 19, Vitest preferido sobre Jest (4-10x mas rapido en watch mode, ESM y TS nativos).
• Carga @.cursor/skills/tests-skill/SKILL.md cuando trabajes con tests unitarios.
• Carga @.cursor/skills/integration-testing-skill/SKILL.md cuando trabajes con tests de integracion (Supertest, MSW, Testcontainers, Pact).
• Carga @.cursor/skills/legacy-testing-skill/SKILL.md cuando generes tests sobre legacy.
• Carga @.cursor/skills/database-skill/SKILL.md cuando generes tests de calidad de datos.
• Carga @.cursor/skills/visual-testing-skill/SKILL.md cuando setupees o amplies tests de UI/a11y.
• Cobertura no es calidad. El comando /cuestionar audita la calidad real con mutation thinking.

BDD (opcional, solo con Three Amigos)

• BDD se adopta vía /bdd y solo si: (a) hay stakeholders no tecnicos que validan criterios, Y (b) el equipo esta dispuesto a hacer Three Amigos.
• Sin conversacion Three Amigos previa, NO escribas .feature files. Gherkin sin conversacion es disfraz tecnico.
• Un solo When por escenario. Lenguaje del dominio, NO de la UI.
• Datos realistas pero minimos. Usar Scenario Outline cuando los casos comparten estructura.
• Herramientas 2026 segun stack: playwright-bdd (JS/TS con UI), @cucumber/cucumber con scope (APIs sin UI), @badeball/cypress-cucumber-preprocessor (Cypress legacy), Reqnroll (.NET, sucesor de SpecFlow), Karate DSL (JVM + APIs).
• Validacion humana del .feature ANTES de generar step definitions.
• Carga @.cursor/skills/bdd-skill/SKILL.md cuando trabajes con BDD.

TESTING CON IA (si aplica)

• Cada test generado por LLM debe tener su *.prompt.md asociado y versionado en Git junto al test.
• PR de tests generados por IA requiere revisor humano explicito. Cero auto-merge.
• Queries accesibles obligatorias (getByRole, getByLabel, getByTestId). Cero selectores de clase, IDs autogenerados o XPath.
• Tests con retry > 0 en main 3 ejecuciones seguidas fallan el pipeline.
• En Cursor, plantilla de Playwright MCP disponible en .cursor/mcp.json (bloque _playwright, renombrar para activar). Alternativa con menor coste en tokens: Playwright CLI para agente con filesystem.
• IA tradicional (ML clasico) gana en self-healing selector-level, flakiness prediction, anomaly detection. LLMs ganan en generacion de tests desde user-story, debugging, Gherkin.
• Antes de enviar datos a LLMs externos: verificar DPA con el proveedor (GDPR). NO enviar PII sin garantias legales.
• Si la app es de alto riesgo bajo EU AI Act (Annex III: empleo, credito, educacion, salud, justicia), los tests forman parte del expediente de calidad y se archivan junto a los prompts y revisiones.
• AI literacy obligatoria desde 2 febrero 2025 para empresas que usan IA.
• Carga @.cursor/skills/ai-testing-skill/SKILL.md cuando uses agentes IA para tests.

BASE DE DATOS (obligatorio si el proyecto tiene BD)

• Todo proyecto nuevo con BD pasa por On(database_setup) despues del testing_setup.
• Toda tabla debe tener primary key y audit fields (createdAt, updatedAt).
• Los campos PII deben identificarse explicitamente y documentarse en docs/database-strategy.md.
• Las foreign keys deben tener regla onDelete explicita.
• En produccion, conexion del MCP de IA a BD SOLO en modo read-only.
• Migraciones destructivas obligatoriamente con patron Expand-Contract.
• Antes de tocar una BD existente, ejecutar On(database_audit) para entender el estado actual.
• Carga @.cursor/skills/database-skill/SKILL.md cuando trabajes con BD.

FRONTEND (obligatorio si el proyecto tiene frontend)

• Todo proyecto nuevo con frontend pasa por On(frontend_setup) despues del testing_setup (y database_setup si aplica).
• Stack canonico 2026: Next.js 15/16 + TypeScript estricto + Tailwind v4 + shadcn/ui + Biome + Zod. Cualquier desviacion se registra como ADR.
• Cero any en codigo de produccion sin justificacion documentada.
• Componentes con responsabilidad unica, <150 lineas orientativas. Si supera, dividir.
• WCAG 2.2 AA como minimo legal (European Accessibility Act vigente desde 28 junio 2025). eslint-plugin-jsx-a11y (o equivalente Biome) y vitest-axe obligatorios.
• Core Web Vitals como Definition of Done: LCP <2.5s, INP <200ms, CLS <0.1.
• Validacion cliente Y servidor con Zod (schemas compartidos). La validacion cliente es UX; la del servidor es seguridad.
• Cero secretos en variables publicas: NEXT_PUBLIC_* / VITE_* / PUBLIC_* no deben contener *_KEY, *_TOKEN, *_SECRET, *_PASSWORD.
• Nunca dangerouslySetInnerHTML sin DOMPurify o equivalente.
• Headers de seguridad configurados (CSP, HSTS, X-Frame-Options, Referrer-Policy) antes de produccion.
• MCP servers recomendados segun escenario: Figma Dev Mode MCP, shadcn MCP, Chrome DevTools MCP, Playwright MCP. Plantillas comentadas en .cursor/mcp.json.
• Vibe coding (v0/Lovable/Bolt) NO se usa para produccion sin revision en Cursor/Claude Code/Windsurf.
• Antes de tocar un frontend existente con cambios estructurales, ejecutar On(frontend_audit) para entender el estado actual.
• Carga @.cursor/skills/frontend-skill/SKILL.md cuando trabajes con frontend.
• Carga @.cursor/skills/visual-testing-skill/SKILL.md cuando setupees o amplies tests de UI/a11y.

SUPPLY CHAIN (obligatorio si el proyecto usa npm registry)

• Todo proyecto nuevo con stack JS/TS pasa por On(supply_chain_setup) durante o despues del testing_setup.
• 4 capas de defensa que el sistema activa por defecto:
  1. Dependency resolution — minimumReleaseAge (cooldown de 1+ dia), blockExoticSubdeps, trustPolicy.
  2. Install-time execution — allowBuilds / ignore-scripts para bloquear scripts arbitrarios.
  3. CI execution — NUNCA pull_request_target con checkout del fork. Pinear acciones a SHA, NO a tag. Permisos minimos por job.
  4. Publish path — OIDC trusted publishing pineado a workflow + branch, branch protection en main, 2FA obligatorio.
• Defaults recomendados por package manager:
  • pnpm 11+: minimumReleaseAge: 1440, blockExoticSubdeps: true, strictDepBuilds: true (ya por defecto).
  • npm 11.10+: min-release-age=2d en .npmrc.
  • Yarn Berry 4.10+: npmMinimalAgeGate: "3d" en .yarnrc.yml.
  • Bun 1.3+: [install] minimumReleaseAge = 259200 en bunfig.toml.
• minimumReleaseAge y allowBuilds NUNCA se desactivan sin ADR documentando el motivo y la fecha de revision.
• En CI usar siempre npm ci / pnpm install --frozen-lockfile / yarn install --immutable / bun install --frozen-lockfile. NUNCA npm install en CI.
• Lockfile (package-lock.json / pnpm-lock.yaml / yarn.lock / bun.lock) SIEMPRE commiteado.
• Respuesta a incidente de paquete comprometido: NO revocar token de GitHub antes de limpiar el daemon de persistencia (vector del ataque TanStack: rm -rf ~/ al revocar). Orden correcto: limpiar persistencia → aislar red → rotar credenciales.
• Antes de tocar un proyecto JS/TS existente sin defensas activas, ejecutar On(supply_chain_audit) para entender el estado actual.
• Carga @.cursor/skills/supply-chain-skill/SKILL.md cuando trabajes con dependencias, lockfiles, workflows de GitHub Actions o publicacion de paquetes.

DECISIONES (trazabilidad)

• Toda decision no trivial se registra en docs/decisions-log.md como una ADR nueva.
• Las ADRs son INMUTABLES: nunca se edita el contenido historico, solo se marca como Superseded por ADR-XXX.
• Son decisiones no triviales: cambio de stack, eleccion de libreria principal, decisiones de arquitectura, cambios de scope de testing, eleccion de motor de BD, eleccion de ORM, decisiones de PII, eleccion de framework frontend, eleccion de libreria de componentes, decisiones de a11y/CWV, MCP servers activados.
• NO son decisiones: bugfixes, renombres, refactors locales, ajustes de estilo.

REGLAS DE ORO

• Centralizacion: Solo se documenta en la raiz de /docs/.
• Fuente de verdad: Docs > memoria auto-generada.
• Sincronizacion: Ticket terminado = [x] en roadmap, % actualizado, tests en verde, Y checklist On(task_complete) visible.
• No proliferacion: No crear archivos nuevos para cambios individuales; editar los maestros.
• Tests como contrato: Un test en verde es un contrato verificable; un test en .skip mas de una semana es un bug del roadmap.
• Decisiones trazables: Si no esta en decisions-log.md, no existe como decision oficial.
• Antidrift: Ninguna tarea se cierra sin mostrar el checklist de sincronizacion documental.
• Legacy primero congelar, luego cambiar: En codigo legacy, nunca modificar sin haber capturado antes el comportamiento actual.
• Cobertura ≠ calidad: Un test que pasa no garantiza que detecte bugs.
• BD primero auditar, luego cambiar: En proyectos con BD, ejecutar /revisar-bd antes de cambios destructivos.
• Frontend primero medir, luego optimizar: En proyectos con frontend, ejecutar /revisar-frontend antes de optimizaciones a ojo. WCAG 2.2 AA y CWV son criterios objetivos. Datos reales (CrUX, axe, lector de pantalla) > intuicion.
• Implementacion paso a paso: Si un plan implica tocar mas de 2 archivos, aplicar On(implementation_phase) con paradas obligatorias entre archivos.
• Prompts profesionales: El usuario consulta @.cursor/skills/prompt-skill/SKILL.md para redactar prompts complejos siguiendo el patron RACEO.
• MCP servers como capacidades: los MCP servers (Figma Dev Mode, shadcn, Chrome DevTools, Playwright, Postgres) extienden lo que el agente puede hacer. Activarlos solo cuando aporten valor al escenario, documentarlos como ADR.
• Codigo IA bajo revision: outputs de v0/Lovable/Bolt/Figma Make pasan obligatoriamente por revision humana en Cursor/Claude Code/Windsurf antes de produccion. ~40-45% tasa de vulnerabilidades en outputs sin revisar.
• BDD sin Three Amigos NO se adopta: Gherkin sin conversacion previa es disfraz tecnico. Si el equipo no esta dispuesto a las conversaciones, mejor NO adoptar BDD.
• Tests IA trazables: Cada test generado por LLM tiene su *.prompt.md asociado, pasa code review humano y NUNCA se mergea por auto-aprobacion.
• AI literacy obligatoria: EU AI Act exige formacion en uso responsable de IA desde febrero 2025. Equipo formado antes de generalizar uso de agentes IA en testing.
• GDPR no negociable: NO enviar PII a LLMs externos sin DPA valido. Para datos sensibles, usar LLMs locales (Ollama, vLLM) o proveedores con region europea y DPA firmado.
• Defensa en 4 capas para supply chain: dependency resolution + install-time execution + CI execution + publish path. minimumReleaseAge (1+ dia) bloquea zero-days de paquetes recien publicados. El ataque TanStack del 11 mayo 2026 demuestra que provenance SLSA valido NO es garantia: defender en capas.
• Lifecycle scripts denegados por defecto: allowBuilds (pnpm) o ignore-scripts (npm) reducen el vector classico de worms npm (postinstall que roba credenciales).
• Respuesta a incidente con orden critico: si se detecta paquete comprometido instalado, NO revocar token de GitHub antes de limpiar daemon de persistencia. Algunos payloads ejecutan rm -rf ~/ al detectar revocacion.