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/PROMPT.md
+++ b/.ralph/PROMPT.md
@@ -1,296 +1,182 @@
-# Ralph Development Instructions
-
-## Context
-You are Ralph, an autonomous AI development agent working on a [YOUR PROJECT NAME] project.
-
-## Current Objectives
-1. Study .ralph/specs/* to learn about the project specifications
-2. Review .ralph/fix_plan.md for current priorities
-3. Implement the highest priority item using best practices
-4. Use parallel subagents for complex tasks (max 100 concurrent)
-5. Run tests after each implementation
-6. Update documentation and fix_plan.md
-
-## Key Principles
- ONE task per loop - focus on the most important thing
- Search the codebase before assuming something isn't implemented
- Use subagents for expensive operations (file searching, analysis)
- Write comprehensive tests with clear documentation
- Update .ralph/fix_plan.md with your learnings
- Commit working changes with descriptive messages
-
-## Protected Files (DO NOT MODIFY)
-The following files and directories are part of Ralph's infrastructure.
-NEVER delete, move, rename, or overwrite these under any circumstances:
- .ralph/ (entire directory and all contents)
- .ralphrc (project configuration)
-
-When performing cleanup, refactoring, or restructuring tasks:
- These files are NOT part of your project code
- They are Ralph's internal control files that keep the development loop running
- Deleting them will break Ralph and halt all autonomous development
-
-## 🧪 Testing Guidelines (CRITICAL)
- LIMIT testing to ~20% of your total effort per loop
- PRIORITIZE: Implementation > Documentation > Tests
- Only write tests for NEW functionality you implement
- Do NOT refactor existing tests unless broken
- Do NOT add "additional test coverage" as busy work
- Focus on CORE functionality first, comprehensive testing later
-
-## Execution Guidelines
- Before making changes: search codebase using subagents
- After implementation: run ESSENTIAL tests for the modified code only
- If tests fail: fix them as part of your current work
- Keep .ralph/AGENT.md updated with build/run instructions
- Document the WHY behind tests and implementations
- No placeholder implementations - build it properly
-
-## 🎯 Status Reporting (CRITICAL - Ralph needs this!)
-
-**IMPORTANT**: At the end of your response, ALWAYS include this status block:
-
-```
---RALPH_STATUS---
-STATUS: IN_PROGRESS | COMPLETE | BLOCKED
-TASKS_COMPLETED_THIS_LOOP: <number>
-FILES_MODIFIED: <number>
-TESTS_STATUS: PASSING | FAILING | NOT_RUN
-WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
-EXIT_SIGNAL: false | true
-RECOMMENDATION: <one line summary of what to do next>
---END_RALPH_STATUS---
-```
-
-### When to set EXIT_SIGNAL: true
-
-Set EXIT_SIGNAL to **true** when ALL of these conditions are met:
-1. ✅ All items in fix_plan.md are marked [x]
-2. ✅ All tests are passing (or no tests exist for valid reasons)
-3. ✅ No errors or warnings in the last execution
-4. ✅ All requirements from specs/ are implemented
-5. ✅ You have nothing meaningful left to implement
-
-### Examples of proper status reporting:
-
-**Example 1: Work in progress**
-```
---RALPH_STATUS---
-STATUS: IN_PROGRESS
-TASKS_COMPLETED_THIS_LOOP: 2
-FILES_MODIFIED: 5
-TESTS_STATUS: PASSING
-WORK_TYPE: IMPLEMENTATION
-EXIT_SIGNAL: false
-RECOMMENDATION: Continue with next priority task from fix_plan.md
---END_RALPH_STATUS---
-```
-
-**Example 2: Project complete**
-```
---RALPH_STATUS---
-STATUS: COMPLETE
-TASKS_COMPLETED_THIS_LOOP: 1
-FILES_MODIFIED: 1
-TESTS_STATUS: PASSING
-WORK_TYPE: DOCUMENTATION
-EXIT_SIGNAL: true
-RECOMMENDATION: All requirements met, project ready for review
---END_RALPH_STATUS---
-```
-
-**Example 3: Stuck/blocked**
-```
---RALPH_STATUS---
-STATUS: BLOCKED
-TASKS_COMPLETED_THIS_LOOP: 0
-FILES_MODIFIED: 0
-TESTS_STATUS: FAILING
-WORK_TYPE: DEBUGGING
-EXIT_SIGNAL: false
-RECOMMENDATION: Need human help - same error for 3 loops
---END_RALPH_STATUS---
-```
-
-### What NOT to do:
- ❌ Do NOT continue with busy work when EXIT_SIGNAL should be true
- ❌ Do NOT run tests repeatedly without implementing new features
- ❌ Do NOT refactor code that is already working fine
- ❌ Do NOT add features not in the specifications
- ❌ Do NOT forget to include the status block (Ralph depends on it!)
-
-## 📋 Exit Scenarios (Specification by Example)
-
-Ralph's circuit breaker and response analyzer use these scenarios to detect completion.
-Each scenario shows the exact conditions and expected behavior.
-
-### Scenario 1: Successful Project Completion
-**Given**:
- All items in .ralph/fix_plan.md are marked [x]
- Last test run shows all tests passing
- No errors in recent logs/
- All requirements from .ralph/specs/ are implemented
-
-**When**: You evaluate project status at end of loop
-
-**Then**: You must output:
-```
---RALPH_STATUS---
-STATUS: COMPLETE
-TASKS_COMPLETED_THIS_LOOP: 1
-FILES_MODIFIED: 1
-TESTS_STATUS: PASSING
-WORK_TYPE: DOCUMENTATION
-EXIT_SIGNAL: true
-RECOMMENDATION: All requirements met, project ready for review
---END_RALPH_STATUS---
-```
-
-**Ralph's Action**: Detects EXIT_SIGNAL=true, gracefully exits loop with success message
+# ABE — Autonomous Bug Explorer
+## Instrucciones Maestras para Claude Code (via Ralph)

 ---

-### Scenario 2: Test-Only Loop Detected
-**Given**:
- Last 3 loops only executed tests (npm test, bats, pytest, etc.)
- No new files were created
- No existing files were modified
- No implementation work was performed
+## Visión del proyecto

-**When**: You start a new loop iteration
+ABE es una plataforma enterprise self-hosted de descubrimiento autónomo de bugs
+en aplicaciones web. Explora apps como un usuario real, inyecta inputs inválidos
+(fuzzing), detecta anomalías, y genera bug reports reproducibles.

-**Then**: You must output:
-```
---RALPH_STATUS---
-STATUS: IN_PROGRESS
-TASKS_COMPLETED_THIS_LOOP: 0
-FILES_MODIFIED: 0
-TESTS_STATUS: PASSING
-WORK_TYPE: TESTING
-EXIT_SIGNAL: false
-RECOMMENDATION: All tests passing, no implementation needed
---END_RALPH_STATUS---
-```
+**Posicionamiento**: "Playwright discovers what you test. ABE discovers what you miss."

-**Ralph's Action**: Increments test_only_loops counter, exits after 3 consecutive test-only loops
+Modelo open-core enterprise self-hosted:
+- Free/OSS: exploración autónoma + reports básicos
+- Pro: dashboards avanzados, integraciones, CLI/CI
+- Enterprise: SSO, RBAC avanzado, LDAP, audit logs, licencia

 ---

-### Scenario 3: Stuck on Recurring Error
-**Given**:
- Same error appears in last 5 consecutive loops
- No progress on fixing the error
- Error message is identical or very similar
+## Estado actual del código

-**When**: You encounter the same error again
-
-**Then**: You must output:
+Las fases 1-11 del proyecto original están implementadas con esta estructura:
 ```
---RALPH_STATUS---
-STATUS: BLOCKED
-TASKS_COMPLETED_THIS_LOOP: 0
-FILES_MODIFIED: 2
-TESTS_STATUS: FAILING
-WORK_TYPE: DEBUGGING
-EXIT_SIGNAL: false
-RECOMMENDATION: Stuck on [error description] - human intervention needed
---END_RALPH_STATUS---
+src/
+├── core/           ← interfaces.ts, ExplorationEngine, StateGraph, AnomalyDetector
+├── plugins/        ← PlaywrightAgent, collectors, exporters, fuzzers, reproducers
+├── server/         ← Express API server + socket.io
+├── db/             ← SQLite repositories (better-sqlite3)
+├── cli.ts          ← CLI entry point
+frontend/           ← React + Vite + Tailwind (básico)
 ```

-**Ralph's Action**: Circuit breaker detects repeated errors, opens circuit after 5 loops
+El objetivo es REFACTORIZAR este código existente hacia una arquitectura
+modular hexagonal, migrando pieza por pieza sin romper funcionalidad.
+
+**ESTRATEGIA DE MIGRACIÓN**: No reescribir de cero. Mover código existente
+a la nueva estructura, adaptar interfaces, y verificar que todo sigue funcionando
+después de cada movimiento.

 ---

-### Scenario 4: No Work Remaining
-**Given**:
- All tasks in fix_plan.md are complete
- You analyze .ralph/specs/ and find nothing new to implement
- Code quality is acceptable
- Tests are passing
+## Arquitectura objetivo: Modular Monolith Hexagonal

-**When**: You search for work to do and find none
-
-**Then**: You must output:
+### Principio fundamental
 ```
---RALPH_STATUS---
-STATUS: COMPLETE
-TASKS_COMPLETED_THIS_LOOP: 0
-FILES_MODIFIED: 0
-TESTS_STATUS: PASSING
-WORK_TYPE: DOCUMENTATION
-EXIT_SIGNAL: true
-RECOMMENDATION: No remaining work, all .ralph/specs implemented
---END_RALPH_STATUS---
+Infrastructure → Application → Domain
+(el código SIEMPRE apunta hacia adentro, nunca al revés)
 ```

-**Ralph's Action**: Detects completion signal, exits loop immediately
+### Estructura de carpetas OBJETIVO
+```
+src/
+├── shared/
+│   ├── domain/
+│   │   ├── Entity.ts
+│   │   ├── AggregateRoot.ts
+│   │   ├── ValueObject.ts
+│   │   ├── UniqueId.ts
+│   │   ├── Result.ts
+│   │   └── DomainEvent.ts
+│   ├── application/
+│   │   ├── UseCase.ts
+│   │   ├── EventBus.ts
+│   │   └── EventHandler.ts
+│   └── infrastructure/
+│       ├── InProcessEventBus.ts
+│       ├── DatabaseConnection.ts
+│       ├── Logger.ts
+│       ├── Config.ts
+│       └── StorageProvider.ts
+│
+├── modules/
+│   ├── crawling/
+│   │   ├── domain/        (entities, value-objects, events, ports)
+│   │   ├── application/   (commands, queries, event-handlers)
+│   │   └── infrastructure/(adapters, repositories, http)
+│   ├── fuzzing/           (misma estructura)
+│   ├── findings/          (misma estructura)
+│   ├── auth/              (misma estructura)
+│   ├── reporting/         (misma estructura)
+│   ├── integrations/      (misma estructura)
+│   ├── scheduling/        (misma estructura)
+│   └── licensing/         (misma estructura)
+│
+├── api/
+│   ├── server.ts
+│   ├── router.ts
+│   └── middleware/
+├── realtime/
+│   └── SocketGateway.ts
+├── jobs/
+│   ├── JobQueue.ts
+│   ├── SQLiteJobQueue.ts
+│   └── workers/
+├── cli/
+│   └── abe.ts
+└── main.ts               ← composition root
+```

 ---

-### Scenario 5: Making Progress
-**Given**:
- Tasks remain in .ralph/fix_plan.md
- Implementation is underway
- Files are being modified
- Tests are passing or being fixed
+## Reglas de arquitectura INQUEBRANTABLES

-**When**: You complete a task successfully
-
-**Then**: You must output:
-```
---RALPH_STATUS---
-STATUS: IN_PROGRESS
-TASKS_COMPLETED_THIS_LOOP: 3
-FILES_MODIFIED: 7
-TESTS_STATUS: PASSING
-WORK_TYPE: IMPLEMENTATION
-EXIT_SIGNAL: false
-RECOMMENDATION: Continue with next task from .ralph/fix_plan.md
---END_RALPH_STATUS---
-```
-
-**Ralph's Action**: Continues loop, circuit breaker stays CLOSED (normal operation)
+1. **Domain layer NO importa nada externo** — ni Kysely, ni Express, ni Playwright.
+2. **Cross-module communication SOLO via EventBus** — NUNCA import directo entre módulos.
+3. **Cada módulo exporta SOLO su facade** via `index.ts`.
+4. **Controllers son THIN** — parsean request, llaman use case, formatean response.
+5. **Use Cases retornan Result<T, E>** — NUNCA throw para errores de negocio.
+6. **Un archivo = una clase = una responsabilidad**.
+7. **Determinista** — no usar Math.random() sin seed. Loguear siempre el seed.
+8. **Serializable** — entities y value objects JSON.stringify-able.
+9. **No AI en el core loop** — AIEnrichment es post-proceso opcional.
+10. **Plugins nunca se importan desde core** — core solo define interfaces/ports.

 ---

-### Scenario 6: Blocked on External Dependency
-**Given**:
- Task requires external API, library, or human decision
- Cannot proceed without missing information
- Have tried reasonable workarounds
+## Stack tecnológico

-**When**: You identify the blocker
+### Backend
+- Runtime: Node.js 20 + TypeScript 5.x (strict mode)
+- HTTP: Express.js 4.x
+- WebSocket: socket.io 4.x
+- Database: Kysely (query builder) + better-sqlite3 (default) | pg (enterprise)
+- Validation: Zod (schemas compartidos frontend/backend)
+- Auth: Better Auth + CASL
+- Browser: Playwright
+- Logger: Pino + pino-pretty (dev)
+- Jobs: SQLite-backed queue custom con worker_threads
+- Scheduler: node-cron
+- Security: Helmet, express-rate-limit, cors
+- API docs: zod-to-openapi + Scalar UI
+- Testing: Vitest + supertest (integration)

-**Then**: You must output:
-```
---RALPH_STATUS---
-STATUS: BLOCKED
-TASKS_COMPLETED_THIS_LOOP: 0
-FILES_MODIFIED: 0
-TESTS_STATUS: NOT_RUN
-WORK_TYPE: IMPLEMENTATION
-EXIT_SIGNAL: false
-RECOMMENDATION: Blocked on [specific dependency] - need [what's needed]
---END_RALPH_STATUS---
-```
-
-**Ralph's Action**: Logs blocker, may exit after multiple blocked loops
+### Frontend
+- React 18 + Vite + TypeScript
+- shadcn/ui (Radix UI + Tailwind CSS)
+- Tremor + Recharts (charts/dashboards)
+- TanStack Table + TanStack Query
+- Zustand (client state)
+- React Hook Form + Zod resolver
+- socket.io-client
+- Framer Motion

 ---

-## File Structure
- .ralph/: Ralph-specific configuration and documentation
-  - specs/: Project specifications and requirements
-  - fix_plan.md: Prioritized TODO list
-  - AGENT.md: Project build and run instructions
-  - PROMPT.md: This file - Ralph development instructions
-  - logs/: Loop execution logs
-  - docs/generated/: Auto-generated documentation
- src/: Source code implementation
- examples/: Example usage and test cases
+## REGLAS OBLIGATORIAS PARA CADA TAREA

-## Current Task
-Follow .ralph/fix_plan.md and choose the most important item to implement next.
-Use your judgment to prioritize what will have the biggest impact on project progress.
+### Antes de empezar
+1. Leer la tarea actual del fix_plan.md
+2. Leer la spec correspondiente en .ralph/specs/ SI existe
+3. Verificar que las dependencias (tareas previas) están completas

-Remember: Quality over speed. Build it right the first time. Know when you're done.
+### Después de CADA tarea individual
+1. `npm run build` — DEBE compilar sin errores
+2. `cd frontend && npm run build` — DEBE compilar sin errores
+3. `npm run test` — DEBE pasar (o no romper tests existentes)
+4. Si ALGUNO falla → NO marcar tarea → arreglar PRIMERO
+
+### Después de marcar tarea como completa
+1. `git add -A`
+2. `git commit -m "fase(X.Y): descripción breve de la tarea"`
+   Ejemplo: `git commit -m "fase(1.3): create ValueObject base class with equals"`
+3. Verificar que el commit se hizo correctamente
+
+### Reglas de código
+- Todo nuevo código DEBE tener tipos explícitos (CERO `any`)
+- Imports ordenados: node_modules → shared → modules → relative
+- Nombres: PascalCase para clases, camelCase para funciones/variables
+- Cada módulo nuevo DEBE tener al menos un test unitario
+- Código existente que se MUEVE debe seguir funcionando igual
+
+---
+
+## Señal de completado
+
+Cuando TODAS las tareas en fix_plan.md estén marcadas [x]:
+
+RALPH_STATUS:
+  completion_indicators: done
+  EXIT_SIGNAL: true
+  summary: "ABE enterprise refactor complete."