CLAUDE.md — Workspace argos-qa

1. Qué es este espacio

Este repositorio es un espacio de documentación y planificación. Su producto son artefactos en markdown: requerimientos funcionales, reglas de negocio, arquitectura, modelo de datos, contratos de integración y el backlog inicial de desarrollo.

No se escribe código de aplicación aquí. Está fuera de alcance, salvo instrucción explícita del usuario:

• Scaffolding de proyectos (package.json, tsconfig.json, vite.config, Dockerfiles…).
• Código fuente de frontend, backend, workers o scripts Playwright.
• Migraciones ejecutables, seeds o infraestructura como código.

Sí es válido incluir dentro de documentos fragmentos ilustrativos: DDL de ejemplo, esquemas JSON, contratos OpenAPI, snippets de payload de eventos y diagramas Mermaid. Son especificación, no implementación.

Cuando llegue el momento de construir, el código vivirá en otros repositorios; este espacio seguirá siendo la fuente de la especificación.

2. El producto que se está especificando

Argos QA — plataforma de gestión de calidad y pruebas asistida por IA.

Nace de una restricción organizacional concreta: no existe un equipo QA dedicado. La validación recae en developers multifunción, y sin un estándar cada uno interpreta distinto qué significa "validado". El objetivo no es construir otra herramienta de gestión de pruebas, sino aterrizar el QA como un proceso guiado, estandarizado y ejecutable por developers, con trazabilidad y evidencia auditable.

Cadena de valor del producto (y también la de esta documentación):

Documento / minuta / ticket
  → Caso de uso
    → Escenario de prueba + criterio de aceptación
      → Dev spec
        → Ticket de desarrollo (Argos Operaciones)
          → Ambiente de pruebas
            → Ciclo de QA → Ejecución → Evidencia
              → Bug / bloqueo → Resolución → Validación final

Decisión de posicionamiento: Argos QA es una plataforma hermana independiente, con su propio repositorio, base de datos, API y despliegue. No reemplaza a Argos Operaciones (argos.flagare), que sigue siendo la fuente de verdad de proyectos, tickets, carga de trabajo y registro de tiempos. La integración es vía API y eventos.

Ecosistema

Módulos

1. AI Workspace — ingesta de documentos, generación y congelamiento de casos de uso.
2. Test Execution Hub — ejecución guiada paso a paso, evidencia, bugs y bloqueos.
3. Portal del Desarrollador — dev specs, criterios, bugs y evidencia accionables.
4. Centro de Observabilidad — cobertura, avance, riesgo de liberación, costos.

3. Alcance vigente de la documentación

Se trabaja por partes. El alcance funcional documentado es el del MVP / Fase 1; lo que pertenezca a fases posteriores se marca como [Fase 2], [Fase 3] o [Fase 4] y no baja a detalle.

Fase de trabajo actual: análisis funcional. Entrega:

• Requerimientos funcionales (RF) y no funcionales (RNF).
• Reglas de negocio (RN) y máquinas de estado.
• Roles y permisos.
• Casos de uso detallados (CU).

Fuera de esta fase (no se produce todavía, aunque las carpetas existan): arquitectura, modelo de datos, contratos de integración y backlog priorizado.

Las especificaciones de desarrollo (dev specs) sí se producen —como historias de usuario en docs/05-especificaciones/, agrupadas por épica, con criterios de aceptación y sin diseño técnico ni plan (DEC-059).

El registro completo de decisiones de alcance está en docs/00-contexto/vision-y-alcance.md (DEC-001 a DEC-061). Lo que sigue abierto está en docs/04-plan/preguntas-abiertas.md.

Definiciones que condicionan cada artefacto

• Cuatro roles de proyecto: Product Manager, QA, Developer, Client (este último,

solo lectura de su propio proyecto).

• Dos roles de plataforma por encima de ellos: Admin (acceso total) y **Product

Manager (importar/crear proyectos), que Argos QA obtiene del servicio /me** de identity.flagare al iniciar sesión (el JWT solo valida identidad; Argos QA no los administra) y son aparte del perfil por proyecto (DEC-060, RN-085).

• Los proyectos de QA se importan desde Argos Operaciones.
• Sincronización con Argos Operaciones: lectura + creación de bugs, no bidireccional completa.
• Autenticación con el JWT propio de Flagare.
• Eventos a notifications.flagare por API; tiempo real en el front por SSE.
• Ingesta limitada a texto pegado y Markdown.
• Evidencia: screenshots, logs y adjuntos. Sin grabación de pantalla en Fase 1.
• La IA propone; todo artefacto admite creación y edición manual.
• Congelamiento de casos de uso: solo el rol Product Manager del proyecto (DEC-037;

la DEC-022 que hablaba de un "aprobador designado" está obsoleta).

• Credenciales de ambiente: solo referencias a un vault existente, nunca valores.
• Dimensionado para 5‑10 proyectos y ~100 ejecuciones/mes.

4. Fuentes de verdad

Política Notion: se lee libremente. No se escribe ni se actualiza ninguna página de Notion salvo que el usuario lo pida de forma explícita. El índice de páginas fuente, con IDs y fechas de captura, está en docs/00-contexto/fuentes-notion.md.

5. Estructura documental

docs/
  00-contexto/        Visión, alcance, ecosistema, glosario, fuentes Notion
  01-requerimientos/  RF, RNF, casos de uso, roles y permisos
  02-reglas-negocio/  Reglas de negocio, máquinas de estado
  03-arquitectura/    Arquitectura, modelo de datos, integraciones, IA,
                      evidencia/storage, seguridad, adr/
  04-plan/            Roadmap, backlog MVP, preguntas abiertas, matriz de trazabilidad
  05-especificaciones/ Historias de usuario (dev specs) y criterios de aceptación
  99-fuentes/         Snapshots read-only de Notion

No se crean archivos placeholder vacíos. Un archivo existe cuando tiene contenido real.

6. Convenciones

Identificadores

Todo artefacto numerado lleva un ID estable. Los IDs no se reutilizan ni se renumeran; si algo se descarta, se marca como obsoleto y su ID queda retirado.

Trazabilidad

La trazabilidad es la tesis del producto, así que la documentación la practica. Cada artefacto declara de qué deriva y qué lo cubre, en una cabecera consistente:

**Deriva de:** CU-003 · **Cubre:** RF-012, RF-013 · **Reglas:** RN-021 · **Estado:** Aprobado

docs/04-plan/matriz-trazabilidad.md consolida la cadena completa. Un RF sin caso de uso de origen, o un CU sin RF que lo cubra, es un hueco y debe aparecer como tal.

Estados de los artefactos de documentación

Borrador → En revisión → Aprobado → Congelado → Obsoleto

(No confundir con los estados del producto —casos de uso, ejecuciones, bugs—, que son parte de la especificación y viven en docs/02-reglas-negocio/.)

Estilo

• Idioma: español. Se conservan en inglés los términos técnicos ya establecidos

en el dominio y en los sistemas existentes: Pass, Fail, Blocked, Not run, Retest required, nombres de tablas, eventos y endpoints.

• Nombres de archivo en kebab-case, sin tildes ni mayúsculas.
• Tablas para enumeraciones comparables; listas para secuencias; Mermaid para flujos,

máquinas de estado y modelo de datos.

• Prosa directa. Sin relleno, sin repetir el mismo punto en tres secciones.
• Fechas absolutas (2026-08-20), nunca "la semana pasada".

7. Cómo debo trabajar en este espacio

1. No inventar decisiones de negocio. Si algo no está en la fuente y no lo definió

el usuario, tiene dos salidas legítimas: una entrada en docs/04-plan/preguntas-abiertas.md (PA-###), o —si es una decisión técnica que puedo fundamentar y proponer— un ADR en estado Propuesto. Nunca darlo por hecho en medio de un requerimiento.

1. Marcar el origen de cada afirmación. Si viene de Notion, referenciar la sección.

Si es una inferencia o propuesta mía, decirlo con esas palabras.

1. Contrastar antes de afirmar. Los snapshots de 99-fuentes/ tienen fecha; si algo

es crítico y el snapshot es viejo, releer Notion antes de asegurarlo.

1. Registrar las contradicciones de la fuente, no resolverlas en silencio. El

material de origen tiene inconsistencias conocidas (ver preguntas abiertas). Se documentan y se preguntan.

1. Mantener la coherencia de IDs. Antes de asignar un RF-### nuevo, verificar el

último usado. Al modificar un artefacto, revisar quién lo referencia.

1. YAGNI en la especificación. Documentar el MVP como se acordó. Una idea buena que

no es del MVP va al roadmap, no al cuerpo de los requerimientos.

8. Git

Repositorio local, rama main. Los commits se hacen solo cuando el usuario lo pide. Mensajes en español, en imperativo, describiendo el artefacto afectado: docs(requerimientos): agregar RF-001 a RF-015 del flujo de ingesta.

9. Estado actual

El análisis funcional del MVP está completo en borrador. Falta la revisión del usuario.

Bloqueado por insumos que el usuario debe entregar: PA-005 (estándar backend Flagare), PA-006 (API de Argos Operaciones), PA-007 (JWT de Flagare), PA-008 (vault de secretos), PA-009 (API de notifications y SSE). Ninguno impide el análisis funcional; todos impiden cerrar los contratos de integración.

PA-002 (resuelta en parte, 2026-08-24 · DEC-059): las dev specs sí se producen, como historias de usuario en docs/05-especificaciones/. Queda abierta solo la parte de GitLab y el Portal del Desarrollador con widgets GitLab, que se resuelve junto con PA-003.