Épica M — Auditoría y trazabilidad

Estado: Borrador · Última actualización: 2026-08-24 · Índice: README

Cubre el registro de auditoría append-only de toda operación relevante y la integridad referencial de la cadena de trazabilidad, que debe poder recorrerse completa y en ambos sentidos. Es un bloque transversal: no deriva de un caso de uso de actor, sino que gobierna a todos los artefactos del sistema. Reglas de negocio del bloque: RN-011, RN-073 a RN-076, más RN-060 en lo que toca al recorrido de la cadena.

HU-027 — Registrar auditoría e integridad referencial

Épica: M · Auditoría y trazabilidad · Deriva de: Transversal · Cubre: RF-131–RF-137 · Reglas: RN-011, RN-073, RN-074, RN-075, RN-076 · Estado: Borrador

Historia

Como plataforma, quiero registrar toda operación relevante en un log inmutable con autor, origen y timestamp, y mantener intacta la cadena de trazabilidad, para que quede evidencia auditable de quién cambió qué y cuándo, y que nunca se rompa el vínculo entre un requerimiento y todo lo que deriva de él.

Objetivo / valor. Que la trazabilidad —tesis del producto— sea verificable: cada cambio crítico deja rastro inmutable con su origen (persona, IA, integración o automatización), y ningún artefacto con derivados puede eliminarse rompiendo la cadena.

Alcance

• Dentro: el registro de cambios críticos con su contenido, la declaración de origen del

cambio, el carácter append-only del log, la consulta filtrable de auditoría, los identificadores estables por artefacto y la integridad referencial que impide eliminar un artefacto con derivados.

• Fuera: qué produce cada operación auditada (vive en su HU), la máquina de estados de

cada entidad y la navegación visual de trazabilidad como reporte (HU-023, RF-111); aquí se garantiza la integridad de la cadena, no su visualización.

Actores y permisos (comportamiento del sistema)

• El registro de auditoría lo escribe el sistema como efecto de cada operación crítica;

ningún rol lo edita ni lo borra —ninguno, incluidos PM y administradores (RN-011, RN-075).

• La consulta de auditoría está disponible para los roles con acceso al proyecto según

la matriz de roles; el Client queda fuera del detalle de auditoría por RN-061.

• La integridad referencial es una garantía del sistema: no depende de la disciplina de

un rol.

Precondiciones

• Ocurre una operación sobre un artefacto crítico: caso de uso, plan, escenario, ambiente,

ciclo, ejecución, bug, bloqueo, rol o aprobación (RF-131).

Comportamiento funcional

• Principal. Toda operación sobre un artefacto crítico genera una entrada de auditoría

con usuario, fecha y hora, acción, artefacto afectado, valor anterior, valor nuevo y justificación cuando aplique, más la declaración de origen del cambio: Usuario, IA, Integración o Automatización. La entrada se agrega al log; el log no admite edición ni borrado por ningún rol.

• Alternativo A1 — consulta. Un usuario con acceso consulta la auditoría filtrando por

artefacto, usuario, rango de fechas, acción y origen (RF-135).

• Alternativo A2 — cambio originado por IA o integración. Cuando el autor material no es

una persona —la IA que escribe un artefacto, Argos Operaciones que crea un ticket espejo—, la entrada declara ese origen, de modo que se distingue lo que hizo una persona de lo que hizo el sistema (RN-074).

• Error E1 — intento de eliminar un artefacto con derivados. El sistema lo impide: el

camino es retirar el artefacto o marcarlo obsoleto, nunca romper la cadena. El identificador del artefacto no se reutiliza aunque se retire (RF-136, RF-137, RN-076).

• Error E2 — intento de editar o borrar auditoría. Rechazado para cualquier rol; el log es

append-only (RN-011, RN-075).

Datos y campos (funcional, no esquema)

• De cada entrada: usuario, fecha y hora, acción, artefacto afectado, valor anterior, valor

nuevo, justificación (cuando aplique), origen (Usuario / IA / Integración / Automatización).

• Del artefacto: identificador estable y legible dentro del proyecto (CU-007, ESC-042,

BUG-013), que no se reutiliza aunque el artefacto se retire.

• De la consulta: filtros por artefacto, usuario, rango de fechas, acción y origen.

Reglas de negocio aplicables

• RN-073 — todo cambio sobre un artefacto crítico registra usuario, fecha y hora, acción,

artefacto, valor anterior, valor nuevo y justificación cuando aplique.

• RN-074 — toda entrada declara su origen: Usuario, IA, Integración o

Automatización.

• RN-011 / RN-075 — el registro de auditoría es append-only: no se edita ni se borra por

ningún rol.

• RN-076 — los identificadores son estables y no se reutilizan; un artefacto con derivados

no se elimina, se retira o se marca obsoleto, y la cadena de trazabilidad no se rompe nunca.

• RN-060 (relacionada) — la cadena requerimiento → caso de uso → escenario → criterio →

ejecución → evidencia → bug → ticket → resolución debe poder recorrerse completa y en ambos sentidos; la integridad referencial de esta HU es lo que garantiza que ese recorrido no tenga eslabones rotos.

Estados y transiciones. No aplica una máquina de estados propia; la auditoría acompaña las transiciones de las máquinas de estado de las demás entidades, registrando cada cambio de estado como una entrada más.

Integraciones (documentado, el dev implementa)

• No introduce integraciones externas propias. Registra, con origen Integración, los

cambios que provienen de sistemas externos ya integrados en otras HU (por ejemplo, el ticket espejo creado en Argos Operaciones desde HU-020, o la importación de proyecto desde HU-003).

Eventos que emite. Ninguno propio. La auditoría es un efecto lateral de las operaciones de negocio; los eventos de dominio los emiten las HU dueñas de cada hito (Épica K).

Criterios de aceptación

• CA-380

> Dado una operación sobre un artefacto crítico (caso, plan, escenario, ambiente, ciclo, ejecución, bug, bloqueo, rol o aprobación) > Cuando la operación se confirma > Entonces se agrega una entrada de auditoría con usuario, fecha y hora, acción, artefacto, valor anterior, valor nuevo y justificación cuando aplique.

• CA-381

> Dado un cambio realizado por la IA o por una integración > Cuando se registra en auditoría > Entonces la entrada declara su origen (Usuario, IA, Integración o Automatización), distinguible del cambio hecho por una persona.

• CA-382

> Dado una entrada de auditoría existente > Cuando cualquier rol intenta editarla o borrarla > Entonces el sistema lo rechaza; el log es append-only.

• CA-383

> Dado un usuario con acceso a la auditoría del proyecto > Cuando consulta filtrando por artefacto, usuario, rango de fechas, acción u origen > Entonces el sistema devuelve las entradas que cumplen el filtro.

• CA-384

> Dado un artefacto que tiene otros artefactos derivados > Cuando se intenta eliminarlo > Entonces el sistema lo impide y ofrece retirarlo o marcarlo obsoleto, sin romper la cadena de trazabilidad.

• CA-385

> Dado un artefacto retirado u obsoleto > Cuando se crea un artefacto nuevo del mismo tipo > Entonces el identificador del artefacto retirado no se reutiliza.

• CA-386

> Dado la cadena de trazabilidad de un proyecto > Cuando se recorre desde un requerimiento hacia sus derivados o desde una resolución hacia su requerimiento de origen > Entonces el recorrido es completo en ambos sentidos, sin eslabones rotos.

Dependencias y bloqueos

• Sin PA que bloquee: la auditoría y la integridad referencial no dependen de insumos

externos pendientes.

• Toda HU que opere sobre artefactos críticos (HU-002 a HU-024) alimenta esta auditoría; esta

HU es la garantía transversal que todas invocan.

Casos borde / notas. "Retirar u obsoletar, nunca eliminar" es la regla que hace que la cadena de RN-060 sea siempre recorrible: un artefacto sin derivados puede desaparecer, pero en cuanto algo deriva de él, su identificador y su rastro quedan. El origen IA en la auditoría es la contraparte de que la IA escriba artefactos (Épica L): sin él no se podría distinguir un caso de uso redactado por una persona de uno propuesto por el modelo.