docs: enterprise refactor plan with ralph specs

2026-03-04 16:17:03 -05:00
parent 4c92712d20
commit f8191133c8
204 changed files with 32722 additions and 422 deletions
--- a/.ralph/specs/legacy/output-format.md
+++ b/.ralph/specs/legacy/output-format.md
@@ -0,0 +1,130 @@
+# ABE — Output Format Specification
+
+Cada anomalía genera DOS archivos en `reports/{anomaly-id}/`:
+
+---
+
+## 1. report.json — Para consumo por AI y tooling
+```json
+{
+  "version": "1.0",
+  "generated_at": "2025-01-15T10:30:00.000Z",
+  "environment": {
+    "target_url": "http://localhost:3000",
+    "abe_version": "0.1.0",
+    "os": "linux",
+    "node_version": "20.x"
+  },
+  "anomaly": {
+    "id": "anom_a1b2c3d4",
+    "type": "http_error",
+    "severity": "high",
+    "description": "Form submission returns HTTP 500 on empty email field",
+    "timestamp": 1705312200000
+  },
+  "reproduction": {
+    "seed": 42,
+    "steps": [
+      {
+        "step": 1,
+        "action_type": "navigate",
+        "url": "http://localhost:3000/register",
+        "timestamp": 1705312195000
+      },
+      {
+        "step": 2,
+        "action_type": "fill",
+        "selector": "input[name='email']",
+        "value": "",
+        "timestamp": 1705312196000
+      },
+      {
+        "step": 3,
+        "action_type": "click",
+        "selector": "button[type='submit']",
+        "timestamp": 1705312197000
+      }
+    ]
+  },
+  "evidence": {
+    "screenshot": "screenshot.png",
+    "dom_snapshot": "dom.html",
+    "http_log": [
+      {
+        "url": "http://localhost:3000/api/register",
+        "method": "POST",
+        "status": 500,
+        "duration_ms": 234
+      }
+    ],
+    "console_errors": [],
+    "js_exceptions": []
+  }
+}
+```
+
+---
+
+## 2. report.md — Para lectura humana
+
+El archivo Markdown debe tener exactamente esta estructura:
+```markdown
+# Bug Report — [tipo de anomalía] — [fecha]
+
+## Summary
+[Una frase describiendo qué pasó y dónde]
+
+## Severity
+[low | medium | high | critical] — [justificación en una frase]
+
+## Reproduction Steps
+
+1. Navigate to `[url]`
+2. [acción 2]
+3. [acción 3]
+...
+
+**Seed used**: `42`
+**Replay command**: `npm run replay -- --report reports/anom_a1b2c3d4/report.json`
+
+## Observed Behavior
+[Qué ocurrió exactamente — errores, respuestas HTTP, mensajes]
+
+## Evidence
+- Screenshot: `reports/anom_a1b2c3d4/screenshot.png`
+- DOM Snapshot: `reports/anom_a1b2c3d4/dom.html`
+- HTTP Log: [tabla con las requests relevantes]
+
+## Raw Errors
+\`\`\`
+[errores textuales tal cual aparecieron]
+\`\`\`
+```
+
+---
+
+## Estructura de carpetas de salida
+```
+reports/
+└── anom_a1b2c3d4/
+    ├── report.json       ← estructurado para AI
+    ├── report.md         ← legible para humanos
+    ├── screenshot.png    ← captura en el momento de la anomalía
+    └── dom.html          ← snapshot completo del DOM
+
+logs/
+└── session_20250115_103000.jsonl   ← una línea JSON por evento
+```
+
+---
+
+## Formato del log de sesión (.jsonl)
+
+Cada línea es un objeto JSON independiente:
+```jsonl
+{"event":"session_start","timestamp":1705312190000,"seed":42,"target":"http://localhost:3000"}
+{"event":"state_discovered","timestamp":1705312191000,"state_id":"s_abc123","url":"/","title":"Home"}
+{"event":"action_executed","timestamp":1705312196000,"action_id":"act_xyz","type":"fill","selector":"input[name='email']","value":""}
+{"event":"anomaly_detected","timestamp":1705312197000,"anomaly_id":"anom_a1b2c3d4","type":"http_error","severity":"high"}
+{"event":"session_end","timestamp":1705312210000,"states_visited":3,"anomalies_found":1}
+```