genoma-evolution 1.0.0

package/.claude/worktrees/phase-2-mcp/.brv/context-tree/backend/backend/main.overview.md

@@ -0,0 +1,30 @@
+# Hermes Evolution Dashboard — Backend Overview
+
+## Key Points
+
+- **FastAPI Backend**: Bridges Next.js frontend to hermes-agent-self-evolution Python modules with REST + WebSocket support
+- **Skill Registry Integration**: Manages skill providers, tracks global/provider-level skills, handles enable/disable and deletion
+- **Evolution Run Tracking**: Lists runs from `metrics.json` files and job tracker, normalizes metrics across different evolve script versions (`evolve_skill.py` vs `evolve_now.py`)
+- **Python Version Detection**: `_find_python()` locates suitable Python executable (prefers 3.12 with dspy installed)
+- **8 API Endpoints** for skill management and evolution monitoring
+- **6 Pydantic Models**: `SkillInfo`, `EvolveRequest`, `MemoryEntry`, `RunMetrics`, `ToggleSkillRequest`, `ConnectionManager`
+
+## Structure / Sections Summary
+
+| Section | Description |
+|---------|-------------|
+| **Imports & Dependencies** | FastAPI, Pydantic, asyncio, JSON, pathlib, subprocess, dotenv |
+| **Paths** | `HERMES_REPO`, `EVOLUTION_DIR`, `SKILLS_DIR`, `MEMORY_DIR` — resolves via env vars or conventional locations |
+| **Classes** | `ConnectionManager` (WebSocket), 5 Pydantic request/response models |
+| **Helper Functions** | `_find_python()`, `_normalize_metrics()`, `_find_skill_file()`, `_parse_skill_content()` |
+| **SKILLS Endpoints** | Provider listing, skill toggling, global/provider skill deletion, skill content retrieval |
+| **EVOLUTION Endpoints** | List all runs, skill-specific history, baseline vs evolved diff |
+
+## Notable Entities & Patterns
+
+- **Environment Variables**: `HERMES_AGENT_REPO`, `EVOLUTION_DIR`, `PYTHON`
+- **Path Resolution Pattern**: Env var → sibling directory → home directory fallback
+- **Metrics Normalization**: Supports multiple evolve script output formats (unifies `skill`/`skill_name`, `original_size`/`baseline_score`, etc.)
+- **WebSocket Broadcasting**: `ConnectionManager` class manages real-time client connections
+- **Job Tracker Integration**: Imports `tracker`, `EvolutionJob`, `JobStatus` from `.job_tracker`
+- **Skill Registry**: Imports `get_registry` from `.skill_registry` for provider/skill management

package/.claude/worktrees/phase-2-mcp/.brv/context-tree/backend/backend/requirements.abstract.md

@@ -0,0 +1 @@
+This document preserves the backend/requirements.txt file from the hermes-dashboard project, containing Python dependencies: fastapi>=0.115.0, uvicorn[standard]>=0.34.0, websockets>=13.0, and pyyaml>=6.0.

package/.claude/worktrees/phase-2-mcp/.brv/context-tree/backend/backend/requirements.md

@@ -0,0 +1,37 @@
+---
+title: requirements
+summary: ''
+tags: []
+related: []
+keywords: []
+createdAt: '2026-04-28T01:33:30.561Z'
+updatedAt: '2026-04-28T01:33:30.562Z'
+---
+## Reason
+Preserving complete backend/requirements.txt from hermes-dashboard project
+
+## Raw Concept
+**Task:**
+Preserve backend/requirements.txt
+
+**Files:**
+- backend/requirements.txt
+
+**Timestamp:** 2026-04-28
+
+## Narrative
+### Structure
+File: backend/requirements.txt, 5 lines
+
+### Highlights
+Source: hermes-dashboard/backend/requirements.txt
+
+---
+
+
+fastapi>=0.115.0
+uvicorn[standard]>=0.34.0
+websockets>=13.0
+pyyaml>=6.0
+
+    

package/.claude/worktrees/phase-2-mcp/.brv/context-tree/backend/backend/requirements.overview.md

@@ -0,0 +1,28 @@
+# Requirements Document Overview
+
+## Key Points
+
+- Preserves `backend/requirements.txt` from the hermes-dashboard project
+- Contains 4 Python dependencies with minimum version constraints
+- Timestamp: 2026-04-28
+- Source location: `hermes-dashboard/backend/requirements.txt`
+- All dependencies are version-pinned with `>=` operators for minimum compatibility
+
+## Structure / Sections Summary
+
+- **Reason**: Documentation metadata noting preservation of the requirements file
+- **Raw Concept**: Task description saving the backend requirements file
+- **Narrative**: Actual file content showing the 4 dependencies
+
+## Notable Entities, Patterns, and Decisions
+
+| Entity | Type | Details |
+|--------|------|---------|
+| `fastapi>=0.115.0` | Dependency | Web framework |
+| `uvicorn[standard]>=0.34.0` | Dependency | ASGI server with standard extras |
+| `websockets>=13.0` | Dependency | WebSocket protocol support |
+| `pyyaml>=6.0` | Dependency | YAML parsing library |
+
+**Pattern**: All dependencies use `>=` minimum version pinning, allowing patch updates without breaking changes.
+
+**Decision**: The file was preserved intact from the hermes-dashboard project, capturing a specific backend dependency snapshot.

package/.claude/worktrees/phase-2-mcp/.brv/context-tree/docs/_index.md

@@ -0,0 +1,37 @@
+---
+children_hash: a71d4119e388f6f696c270fd1202587c41019b22b842e94859adf7c2d81eff99
+compression_ratio: 0.5456349206349206
+condensation_order: 2
+covers: [api/_index.md]
+covers_token_total: 504
+summary_level: d2
+token_count: 275
+type: summary
+---
+# docs/api — Hermes API Specification
+
+## Architecture
+OpenAPI 3.0 contract between Next.js frontend and FastAPI backend. Backend runs at `http://127.0.0.1:8000` (configurable via `NEXT_PUBLIC_API_BASE`).
+
+## Endpoints
+
+| Group | Methods |
+|-------|---------|
+| Skills | `GET /api/skills`, `GET /api/skills/{name}`, `GET /api/skills/{name}/evolution-history` |
+| Evolution | `GET /api/evolution/runs`, `POST /api/evolution/start` |
+| Jobs | `GET /api/jobs`, `GET /api/jobs/{jobId}`, `DELETE /api/jobs/{jobId}`, `GET /api/jobs/{jobId}/logs` |
+| Health | `GET /api/health` |
+| Realtime | `/ws` |
+
+## Key Schemas
+
+**EvolutionJob lifecycle:** `queued → loading_skill → building_dataset → validating → configuring → optimizing → evaluating → saving → completed/failed`
+
+**ApiError kinds:** `network`, `timeout`, `server` (5xx), `client` (4xx)
+
+**EvolutionRun:** tracks `baseline_score`, `evolved_score`, `improvement`, `constraints_passed`
+
+## Drill-down
+- Full spec: `hermes_api_openapi_specification.md`
+- Backend: `backend/main.py`, `backend/job_tracker.py`
+- Frontend client: `frontend/src/lib/api.ts`

package/.claude/worktrees/phase-2-mcp/.brv/context-tree/docs/api/_index.md

@@ -0,0 +1,54 @@
+---
+children_hash: 50c773b90f6937381a937265ca7c7ce8090632fd257e370e2bd838288f3232dd
+compression_ratio: 0.12634643377001456
+condensation_order: 1
+covers: [context.md, hermes_api_openapi_specification.md]
+covers_token_total: 3435
+summary_level: d1
+token_count: 434
+type: summary
+---
+# docs/api — API Specification Domain
+
+## Overview
+OpenAPI 3.0 specification documenting the Hermes backend API contract. Next.js frontend consumes these endpoints; FastAPI/Python backend exposes them at `http://127.0.0.1:8000` (overridable via `NEXT_PUBLIC_API_BASE`).
+
+## Endpoint Groups
+
+### Skills
+- `GET /api/skills` — List all installed skills
+- `GET /api/skills/{name}` — Get skill detail (frontmatter + body)
+- `GET /api/skills/{name}/evolution-history` — Get evolution history for skill
+
+### Evolution
+- `GET /api/evolution/runs` — List all evolution runs
+- `POST /api/evolution/start` — Start evolution job (`skill_name`, `iterations` 1-20, `eval_source`)
+
+### Jobs
+- `GET /api/jobs` — List jobs (optional `active_only` filter)
+- `GET /api/jobs/{jobId}` — Get job detail
+- `DELETE /api/jobs/{jobId}` — Cancel active job
+- `GET /api/jobs/{jobId}/logs` — Get paginated logs (`since` param)
+
+### Health
+- `GET /api/health` — Returns `status`, `hermes_repo_exists`, `evolution_dir_exists`, `skills_count`, `categories`
+
+### WebSocket
+- `/ws` — Real-time job progress streaming
+
+## Key Schemas
+
+**EvolutionJob status flow:** `queued → loading_skill → building_dataset → validating → configuring → optimizing → evaluating → saving → completed/failed`
+
+**ApiError** — Typed error contract with `kind` enum:
+- `network` — Service unreachable
+- `timeout` — Request timeout exceeded
+- `server` — HTTP 5xx
+- `client` — HTTP 4xx
+
+**EvolutionRun** — Records `baseline_score`, `evolved_score`, `improvement`, `constraints_passed` per run
+
+## Related Entries
+- See `hermes_api_openapi_specification.md` for full OpenAPI YAML
+- Backend implementation: `backend/main.py`, `backend/job_tracker.py`
+- Frontend client: `frontend/src/lib/api.ts`

package/.claude/worktrees/phase-2-mcp/.brv/context-tree/docs/api/context.md

@@ -0,0 +1,11 @@
+# Topic: api
+
+## Overview
+OpenAPI 3.0 specification for Hermes agent self-evolution backend
+
+## Key Concepts
+- Job management API
+- Skills registry
+- Evolution endpoints
+- WebSocket streaming
+- Configuration management

package/.claude/worktrees/phase-2-mcp/.brv/context-tree/docs/api/hermes_api_openapi_specification.md

@@ -0,0 +1,468 @@
+---
+title: Hermes API OpenAPI Specification
+summary: Complete OpenAPI 3.0 specification defining all Hermes backend endpoints including job management, skills, evolution, and WebSocket streaming
+tags: []
+related: []
+keywords: []
+createdAt: '2026-04-28T03:39:56.018Z'
+updatedAt: '2026-04-28T03:46:41.133Z'
+---
+## Reason
+Preserving complete OpenAPI 3.0 spec for Hermes backend API
+
+## Raw Concept
+**Task:**
+Document Hermes backend API specification
+
+**Files:**
+- docs/api/hermes-api.openapi.yaml
+
+**Timestamp:** 2026-04-28
+
+## Narrative
+### Structure
+OpenAPI 3.0 specification with paths for /jobs, /skills, /evolve, /config, and WebSocket /ws endpoint
+
+---
+
+
+openapi: "3.1.0"
+info:
+  title: Hermes Agent API
+  description: |
+    API del backend de Hermes (FastAPI/Python) expuesta por el gateway de hermes-cli.
+    El frontend Next.js consume estos endpoints y espera este contrato de respuesta.
+  version: "1.0.0"
+  contact:
+    name: Hermes Dashboard
+
+servers:
+  - url: "http://127.0.0.1:8000"
+    description: Backend local (default). NEXT_PUBLIC_API_BASE sobreescribe esta URL.
+
+paths:
+  ## ── Skills ──────────────────────────────────────────────────────────
+  /api/skills:
+    get:
+      operationId: listSkills
+      summary: Listar todos los skills instalados
+      description: Retorna la lista completa de skills detectados en los directorios configurados.
+      responses:
+        "200":
+          description: Lista de skills
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/SkillInfo"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /api/skills/{name}:
+    get:
+      operationId: getSkill
+      summary: Obtener detalle de un skill
+      description: Retorna el contenido completo de un skill incluyendo frontmatter y body.
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Detalle del skill
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SkillDetail"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /api/skills/{name}/evolution-history:
+    get:
+      operationId: getSkillHistory
+      summary: Historial de evolución de un skill
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Lista de ejecuciones de evolución para este skill
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/EvolutionRun"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  ## ── Evolution ───────────────────────────────────────────────────────
+  /api/evolution/runs:
+    get:
+      operationId: listEvolutionRuns
+      summary: Listar todas las ejecuciones de evolución
+      description: Retorna el historial completo de ejecuciones de evolución.
+      responses:
+        "200":
+          description: Lista de runs de evolución
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/EvolutionRun"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /api/evolution/start:
+    post:
+      operationId: startEvolution
+      summary: Iniciar una evolución
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [skill_name, iterations]
+              properties:
+                skill_name:
+                  type: string
+                  description: Nombre del skill a evolucionar
+                iterations:
+                  type: integer
+                  minimum: 1
+                  maximum: 20
+                  default: 3
+                eval_source:
+                  type: string
+                  default: synthetic
+      responses:
+        "200":
+          description: Job de evolución creado
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  job_id:
+                    type: string
+                  skill:
+                    type: string
+                  status:
+                    type: string
+                  error:
+                    type: string
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  ## ── Jobs ───────────────────────────────────────────────────────────
+  /api/jobs:
+    get:
+      operationId: listJobs
+      summary: Listar jobs activos o todos
+      parameters:
+        - name: active_only
+          in: query
+          schema:
+            type: boolean
+            default: false
+      responses:
+        "200":
+          description: Lista de jobs
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/EvolutionJob"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /api/jobs/{jobId}:
+    get:
+      operationId: getJob
+      summary: Obtener detalle de un job
+      parameters:
+        - name: jobId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Detalle del job
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvolutionJob"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+    delete:
+      operationId: cancelJob
+      summary: Cancelar un job activo
+      parameters:
+        - name: jobId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Job cancelado
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /api/jobs/{jobId}/logs:
+    get:
+      operationId: getJobLogs
+      summary: Obtener logs de un job
+      parameters:
+        - name: jobId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: since
+          in: query
+          schema:
+            type: integer
+            default: 0
+      responses:
+        "200":
+          description: Logs del job (streaming paginado)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  job_id:
+                    type: string
+                  total_lines:
+                    type: integer
+                  logs:
+                    type: array
+                    items:
+                      type: string
+                  status:
+                    type: string
+                  progress:
+                    type: number
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  ## ── Health ─────────────────────────────────────────────────────────
+  /api/health:
+    get:
+      operationId: healthCheck
+      summary: Health check del backend
+      responses:
+        "200":
+          description: Estado del sistema
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: ok
+                  hermes_repo:
+                    type: string
+                  hermes_repo_exists:
+                    type: boolean
+                  evolution_dir:
+                    type: string
+                  evolution_dir_exists:
+                    type: boolean
+                  skills_count:
+                    type: integer
+                  categories:
+                    type: object
+                    additionalProperties:
+                      type: integer
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+## ── Componentes ─────────────────────────────────────────────────────
+components:
+  schemas:
+    SkillInfo:
+      type: object
+      required: [name, path, description, size, last_modified, providers, provider_count, category]
+      properties:
+        name:
+          type: string
+          example: accessibility
+        path:
+          type: string
+          example: /home/user/.agents/skills/accessibility
+        description:
+          type: string
+        size:
+          type: number
+        last_modified:
+          type: string
+          format: date-time
+        providers:
+          type: array
+          items:
+            type: string
+        provider_count:
+          type: integer
+        category:
+          type: string
+
+    SkillDetail:
+      type: object
+      required: [name, path, frontmatter, body, raw, size]
+      properties:
+        name:
+          type: string
+        path:
+          type: string
+        frontmatter:
+          type: object
+          additionalProperties: true
+          description: YAML frontmatter parseado
+        body:
+          type: string
+          description: Contenido Markdown sin frontmatter
+        raw:
+          type: string
+          description: Archivo completo sin procesar
+        size:
+          type: number
+
+    EvolutionRun:
+      type: object
+      required:
+        [skill_name, timestamp, baseline_score, evolved_score, improvement,
+         elapsed_seconds, constraints_passed, iterations, optimizer_model]
+      properties:
+        skill_name:
+          type: string
+        timestamp:
+          type: string
+        baseline_score:
+          type: number
+          description: Score pre-evolución (0-1)
+        evolved_score:
+          type: number
+          description: Score post-evolución (0-1)
+        improvement:
+          type: number
+          description: Diferencia (positivo = mejoró)
+        elapsed_seconds:
+          type: number
+        constraints_passed:
+          type: boolean
+        iterations:
+          type: integer
+        optimizer_model:
+          type: string
+
+    EvolutionJob:
+      type: object
+      properties:
+        id:
+          type: string
+        skill_name:
+          type: string
+        status:
+          type: string
+          enum:
+            [queued, loading_skill, building_dataset, validating,
+             configuring, optimizing, evaluating, saving, completed, failed]
+        iterations:
+          type: integer
+        current_iteration:
+          type: integer
+        pid:
+          type: integer
+          nullable: true
+        started_at:
+          type: string
+        completed_at:
+          type: string
+        baseline_score:
+          type: number
+          nullable: true
+        current_best_score:
+          type: number
+          nullable: true
+        evolved_score:
+          type: number
+          nullable: true
+        improvement:
+          type: number
+          nullable: true
+        error:
+          type: string
+        progress:
+          type: number
+        logs:
+          type: array
+          items:
+            type: string
+
+    ## ── Error tipado ─────────────────────────────────────────────────
+    ApiError:
+      type: object
+      description: |
+        Contrato de error que el frontend debe interpretar.
+        Cualquier respuesta != 2xx o error de red se mapea a esta estructura.
+      required: [kind, message]
+      properties:
+        kind:
+          type: string
+          enum: [network, timeout, server, client]
+          description: |
+            network  → fetch() rechazó (servicio no alcanzable)
+            timeout  → AbortController superó el límite
+            server   → HTTP 5xx
+            client   → HTTP 4xx
+        message:
+          type: string
+          description: Texto legible para UI
+        status:
+          type: integer
+          description: Código HTTP (solo en server y client)
+        endpoint:
+          type: string
+          description: Ruta que falló (para diagnóstico)
+
+    ## ── Health fallback ──────────────────────────────────────────────
+    HealthStatus:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [ok, disconnected]
+        lastSeen:
+          type: string
+          format: date-time
+          description: Última vez que /api/health respondió 200
+
+  ## ── Respuesta 503 estandarizada ───────────────────────────────────
+  responses:
+    ServiceUnavailable:
+      description: >
+        El backend no está alcanzable. El frontend debe interpretar esto como señal
+        para mostrar estado "Desconectado" con opción de reintento.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ApiError"
+          example:
+            kind: network
+            message: "El servicio de Hermes no está disponible"
+            endpoint: "/api/skills"
+
+