genoma-evolution 1.0.0

package/.claude/worktrees/phase-2-mcp/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "hermes-dashboard",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@chenglou/pretext": "^0.0.6",
+    "@tanstack/react-query": "^5.99.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "framer-motion": "^12.38.0",
+    "lucide-react": "^1.8.0",
+    "next": "^16.2.6",
+    "next-themes": "^0.4.6",
+    "radix-ui": "^1.4.3",
+    "react": "19.2.4",
+    "react-bits": "^1.0.5",
+    "react-dom": "19.2.4",
+    "shadcn": "^4.4.0",
+    "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0",
+    "vis-data": "^8.0.3",
+    "vis-network": "^10.0.2"
+  },
+  "devDependencies": {
+    "@next/bundle-analyzer": "^16.2.4",
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.4",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

package/.claude/worktrees/phase-2-mcp/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+allowBuilds:
+  msw: set this to true or false
+  sharp: set this to true or false
+  unrs-resolver: set this to true or false

package/.claude/worktrees/phase-2-mcp/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/.claude/worktrees/phase-2-mcp/public/file.svg

@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

package/.claude/worktrees/phase-2-mcp/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

package/.claude/worktrees/phase-2-mcp/public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

package/.claude/worktrees/phase-2-mcp/public/theme-preview.html

@@ -0,0 +1,257 @@
+<!DOCTYPE html>
+<html lang="es">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Genoma — Light Theme Preview</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script>
+    tailwind.config = {
+      theme: {
+        extend: {
+          colors: {
+            base: '#F4F7FA',
+            surface: '#FFFFFF',
+            'surface-hover': '#F0F4F8',
+            primary: {
+              50: '#ECFEFF', 100: '#CFFAFE', 200: '#A5F3FC',
+              300: '#67E8F9', 400: '#22D3EE', 500: '#06B6D4',
+              600: '#0891B2', 700: '#0E7490', 800: '#155E75', 900: '#164E63',
+            },
+            semantic: {
+              success: '#2DD4BF', warning: '#FBBF24',
+              error: '#E11D48', info: '#0EA5E9',
+            },
+            txt: {
+              primary: '#0F172A', secondary: '#475569',
+              tertiary: '#94A3B8', inverse: '#F8FAFC',
+            }
+          },
+          boxShadow: {
+            'evo-sm': '0 1px 2px 0 rgba(15, 23, 42, 0.05)',
+            'evo-md': '0 4px 6px -1px rgba(15, 23, 42, 0.08), 0 2px 4px -2px rgba(15, 23, 42, 0.04)',
+            'evo-lg': '0 10px 15px -3px rgba(15, 23, 42, 0.08), 0 4px 6px -4px rgba(15, 23, 42, 0.04)',
+            'evo-glow': '0 0 0 3px rgba(6, 182, 212, 0.15)',
+          }
+        }
+      }
+    }
+  </script>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+  <style>body { font-family: 'Inter', sans-serif; }</style>
+</head>
+<body class="bg-base min-h-screen">
+  <!-- Sidebar -->
+  <div class="fixed left-0 top-0 h-full w-16 bg-surface border-r border-gray-200 flex flex-col items-center py-6 gap-4 z-50">
+    <div class="w-10 h-10 rounded-xl bg-primary-600 flex items-center justify-center text-white font-bold text-lg">G</div>
+    <div class="w-8 h-8 rounded-lg bg-primary-50 text-primary-700 flex items-center justify-center text-sm">🏠</div>
+    <div class="w-8 h-8 rounded-lg bg-primary-600 text-white flex items-center justify-center text-sm shadow-evo-md">⚡</div>
+    <div class="w-8 h-8 rounded-lg hover:bg-surface-hover text-txt-secondary flex items-center justify-center text-sm transition-colors">📊</div>
+    <div class="w-8 h-8 rounded-lg hover:bg-surface-hover text-txt-secondary flex items-center justify-center text-sm transition-colors">🧠</div>
+  </div>
+
+  <!-- Main Content -->
+  <div class="ml-16 p-8">
+    <!-- Header -->
+    <div class="flex items-center justify-between mb-8">
+      <div class="flex items-center gap-3">
+        <div class="w-10 h-10 rounded-xl bg-primary-100 flex items-center justify-center">
+          <span class="text-xl">⚡</span>
+        </div>
+        <div>
+          <h1 class="text-2xl font-bold text-txt-primary">Skill Hub</h1>
+          <p class="text-sm text-txt-secondary">Tus skills locales, organizadas por proveedor y categoría</p>
+        </div>
+      </div>
+      <div class="flex items-center gap-3">
+        <button class="px-4 py-2 bg-primary-600 text-white rounded-lg text-sm font-medium hover:bg-primary-700 transition-colors shadow-evo-md">
+          🎨 Aplicar Tema
+        </button>
+        <button class="px-4 py-2 bg-surface border border-gray-200 text-txt-secondary rounded-lg text-sm hover:bg-surface-hover transition-colors">
+          🔄 Refresh
+        </button>
+      </div>
+    </div>
+
+    <!-- Search + Filters -->
+    <div class="flex gap-4 mb-6">
+      <div class="relative flex-1">
+        <span class="absolute left-3 top-1/2 -translate-y-1/2 text-txt-tertiary">🔍</span>
+        <input type="text" placeholder="Buscar skills por nombre, descripción o categoría..."
+          class="w-full pl-10 pr-4 py-3 bg-surface border border-gray-200 rounded-xl focus:outline-none focus:ring-2 focus:ring-primary-500/30 focus:border-primary-400 text-txt-primary shadow-evo-sm"
+        />
+      </div>
+      <select class="px-4 py-3 bg-surface border border-gray-200 rounded-xl text-txt-secondary focus:outline-none focus:ring-2 focus:ring-primary-500/30 shadow-evo-sm">
+        <option>Todos los providers</option>
+        <option>Agency</option>
+        <option>Hermes</option>
+      </select>
+      <select class="px-4 py-3 bg-surface border border-gray-200 rounded-xl text-txt-secondary focus:outline-none focus:ring-2 focus:ring-primary-500/30 shadow-evo-sm">
+        <option>Todas las categorías</option>
+        <option>software-development</option>
+        <option>devops</option>
+      </select>
+    </div>
+
+    <!-- Stats Cards -->
+    <div class="grid grid-cols-4 gap-4 mb-8">
+      <div class="bg-surface rounded-2xl border border-gray-100 p-5 shadow-evo-md hover:shadow-evo-lg transition-shadow">
+        <div class="text-2xl mb-2">🏢</div>
+        <div class="text-sm font-medium text-txt-secondary capitalize">Agency</div>
+        <div class="text-3xl font-bold text-primary-700 mt-1">1173/1185</div>
+        <div class="text-xs text-txt-tertiary mt-1">habilitadas</div>
+      </div>
+      <div class="bg-surface rounded-2xl border border-gray-100 p-5 shadow-evo-md hover:shadow-evo-lg transition-shadow">
+        <div class="text-2xl mb-2">🪽</div>
+        <div class="text-sm font-medium text-txt-secondary capitalize">Hermes</div>
+        <div class="text-3xl font-bold text-primary-700 mt-1">127/127</div>
+        <div class="text-xs text-txt-tertiary mt-1">habilitadas</div>
+      </div>
+      <div class="bg-surface rounded-2xl border border-gray-100 p-5 shadow-evo-md hover:shadow-evo-lg transition-shadow">
+        <div class="text-2xl mb-2">🤖</div>
+        <div class="text-sm font-medium text-txt-secondary capitalize">Claude-Code</div>
+        <div class="text-3xl font-bold text-primary-700 mt-1">99/99</div>
+        <div class="text-xs text-txt-tertiary mt-1">habilitadas</div>
+      </div>
+      <div class="bg-surface rounded-2xl border border-gray-100 p-5 shadow-evo-md hover:shadow-evo-lg transition-shadow">
+        <div class="text-2xl mb-2">⚡</div>
+        <div class="text-sm font-medium text-txt-secondary capitalize">Kilocode</div>
+        <div class="text-3xl font-bold text-primary-700 mt-1">27/27</div>
+        <div class="text-xs text-txt-tertiary mt-1">habilitadas</div>
+      </div>
+    </div>
+
+    <!-- Provider: Hermes (Expanded) -->
+    <div class="bg-surface rounded-2xl border border-gray-100 shadow-evo-md overflow-hidden mb-6">
+      <div class="flex items-center justify-between p-5 cursor-pointer hover:bg-surface-hover transition-colors">
+        <div class="flex items-center gap-3">
+          <span class="text-2xl">🪽</span>
+          <div>
+            <h2 class="text-lg font-bold text-txt-primary capitalize">Hermes</h2>
+            <p class="text-xs text-txt-tertiary">25 categorías</p>
+          </div>
+        </div>
+        <div class="flex items-center gap-4">
+          <span class="text-sm text-txt-secondary">127/127 activas</span>
+          <span class="text-txt-tertiary">▼</span>
+        </div>
+      </div>
+
+      <div class="px-5 pb-5 space-y-3">
+        <!-- Category: software-development -->
+        <div class="border border-gray-100 rounded-xl overflow-hidden">
+          <div class="flex items-center justify-between p-3 hover:bg-base transition-colors cursor-pointer">
+            <div class="flex items-center gap-2">
+              <span class="text-gray-400">📁</span>
+              <span class="text-sm font-semibold text-primary-700 bg-primary-50 px-2 py-0.5 rounded-lg border border-primary-200">
+                software-development
+              </span>
+              <span class="text-xs text-txt-tertiary">32 skills</span>
+            </div>
+            <span class="text-txt-tertiary text-sm">▼</span>
+          </div>
+          <div class="p-3 pt-0 grid grid-cols-3 gap-2">
+            <div class="p-3 bg-base rounded-lg border border-gray-100 hover:border-primary-300 hover:shadow-evo-sm transition-all">
+              <div class="flex items-start justify-between">
+                <div>
+                  <h3 class="font-medium text-txt-primary text-sm">python-cli-to-dashboard</h3>
+                  <p class="text-xs text-txt-secondary mt-1">Wrap Python CLI in FastAPI</p>
+                </div>
+                <div class="w-8 h-8 rounded-lg bg-semantic-success/10 text-semantic-success flex items-center justify-center text-xs">✓</div>
+              </div>
+            </div>
+            <div class="p-3 bg-base rounded-lg border border-gray-100 hover:border-primary-300 hover:shadow-evo-sm transition-all">
+              <div class="flex items-start justify-between">
+                <div>
+                  <h3 class="font-medium text-txt-primary text-sm">tauri-linux-compat</h3>
+                  <p class="text-xs text-txt-secondary mt-1">Port Tauri to Linux</p>
+                </div>
+                <div class="w-8 h-8 rounded-lg bg-semantic-success/10 text-semantic-success flex items-center justify-center text-xs">✓</div>
+              </div>
+            </div>
+            <div class="p-3 bg-base rounded-lg border border-gray-100 hover:border-primary-300 hover:shadow-evo-sm transition-all">
+              <div class="flex items-start justify-between">
+                <div>
+                  <h3 class="font-medium text-txt-primary text-sm">test-driven-dev</h3>
+                  <p class="text-xs text-txt-secondary mt-1">TDD workflow</p>
+                </div>
+                <div class="w-8 h-8 rounded-lg bg-semantic-success/10 text-semantic-success flex items-center justify-center text-xs">✓</div>
+              </div>
+            </div>
+          </div>
+          <button class="w-full py-2 text-sm text-primary-600 hover:text-primary-700 hover:bg-primary-50 transition-colors border-t border-dashed border-gray-200">
+            Mostrar más (29 restantes)
+          </button>
+        </div>
+
+        <!-- Category: devops -->
+        <div class="border border-gray-100 rounded-xl overflow-hidden">
+          <div class="flex items-center justify-between p-3 hover:bg-base transition-colors cursor-pointer">
+            <div class="flex items-center gap-2">
+              <span class="text-gray-400">📁</span>
+              <span class="text-sm font-semibold text-semantic-info bg-sky-50 px-2 py-0.5 rounded-lg border border-sky-200">
+                devops
+              </span>
+              <span class="text-xs text-txt-tertiary">16 skills</span>
+            </div>
+            <span class="text-txt-tertiary text-sm">▼</span>
+          </div>
+        </div>
+
+        <!-- Category: github -->
+        <div class="border border-gray-100 rounded-xl overflow-hidden">
+          <div class="flex items-center justify-between p-3 hover:bg-base transition-colors cursor-pointer">
+            <div class="flex items-center gap-2">
+              <span class="text-gray-400">📁</span>
+              <span class="text-sm font-semibold text-orange-600 bg-orange-50 px-2 py-0.5 rounded-lg border border-orange-200">
+                github
+              </span>
+              <span class="text-xs text-txt-tertiary">6 skills</span>
+            </div>
+            <span class="text-txt-tertiary text-sm">▼</span>
+          </div>
+        </div>
+
+        <!-- Category: creative -->
+        <div class="border border-gray-100 rounded-xl overflow-hidden">
+          <div class="flex items-center justify-between p-3 hover:bg-base transition-colors cursor-pointer">
+            <div class="flex items-center gap-2">
+              <span class="text-gray-400">📁</span>
+              <span class="text-sm font-semibold text-purple-600 bg-purple-50 px-2 py-0.5 rounded-lg border border-purple-200">
+                creative
+              </span>
+              <span class="text-xs text-txt-tertiary">13 skills</span>
+            </div>
+            <span class="text-txt-tertiary text-sm">▼</span>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Provider: Claude-Code (Collapsed) -->
+    <div class="bg-surface rounded-2xl border border-gray-100 shadow-evo-sm overflow-hidden mb-6">
+      <div class="flex items-center justify-between p-5 cursor-pointer hover:bg-surface-hover transition-colors">
+        <div class="flex items-center gap-3">
+          <span class="text-2xl">🤖</span>
+          <div>
+            <h2 class="text-lg font-bold text-txt-primary capitalize">Claude-Code</h2>
+            <p class="text-xs text-txt-tertiary">1 categoría</p>
+          </div>
+        </div>
+        <div class="flex items-center gap-4">
+          <span class="text-sm text-txt-secondary">99/99 activas</span>
+          <span class="text-txt-tertiary">▶</span>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Floating Theme Toggle -->
+  <div class="fixed bottom-6 right-6 flex gap-2">
+    <div class="bg-surface border border-gray-200 rounded-xl p-1 shadow-evo-lg flex gap-1">
+      <button class="px-3 py-1.5 rounded-lg bg-primary-600 text-white text-sm font-medium">☀️ Light</button>
+      <button class="px-3 py-1.5 rounded-lg hover:bg-gray-100 text-txt-secondary text-sm transition-colors">🌙 Dark</button>
+    </div>
+  </div>
+</body>
+</html>

package/.claude/worktrees/phase-2-mcp/public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

package/.claude/worktrees/phase-2-mcp/public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

package/.claude/worktrees/phase-2-mcp/run.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -e
+
+cd /Users/leandrothomas/Desktop/Projects/genoma
+
+# Install deps once (silent)
+echo "Installing dependencies..."
+python3 -m pip install fastapi uvicorn pydantic python-dotenv --break-system-packages -q 2>/dev/null || true
+pnpm install --ignore-scripts -q 2>/dev/null || true
+
+echo "Starting backend on :8000..."
+python3 -m uvicorn backend.main:app --reload --port 8000 &
+BACKEND_PID=$!
+
+echo "Starting MCP server (stdio)..."
+python3 -m backend.mcp_server &
+MCP_PID=$!
+
+echo "Starting frontend on :3000..."
+sleep 2
+
+# Kill backend + MCP if script exits
+trap "kill $BACKEND_PID $MCP_PID 2>/dev/null || true" EXIT
+
+# Run frontend (foreground — Ctrl+C kills both)
+pnpm dev

package/.claude/worktrees/phase-2-mcp/skills-lock.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "skills": {
+    "frontend-design": {
+      "source": "anthropics/skills",
+      "sourceType": "github",
+      "computedHash": "063a0e6448123cd359ad0044cc46b0e490cc7964d45ef4bb9fd842bd2ffbca67"
+    }
+  }
+}

package/.claude/worktrees/phase-2-mcp/specs/event-schema.md

@@ -0,0 +1,223 @@
+# Canonical Run Event Schema v0.1
+
+## Purpose
+
+Define a vendor-neutral event format for agent execution telemetry. Any agent (Hermes, Claude Code, Codex, OpenCode) can emit runs in this schema. The schema is the single source of truth for cross-agent comparison, evaluation, and regression detection.
+
+---
+
+## Design Principles
+
+1. **Agent-agnostic:** No special cases for any single agent. Required fields are minimal; optional fields capture agent-specific context.
+2. **Append-only:** New fields may be added to optional sections. Removing or renaming required fields is breaking.
+3. **Graceful degradation:** Missing optional fields never break ingestion. Unknown fields go into `context{}` dict.
+4. **Deterministic evaluation:** The same run, evaluated twice, always produces identical scores.
+5. **Cross-comparable:** Two runs from different agents can be compared on: outcome, token usage, tool calls, errors, improvement delta.
+
+---
+
+## Root Object: `CanonicalRun`
+
+### Required Fields
+
+These fields MUST be present and non-null for a valid run event. Collectors must fail fast if unable to provide them.
+
+| Field | Type | Example | Notes |
+|-------|------|---------|-------|
+| `run_id` | string (UUID) | `"a1b2c3d4-e5f6-..."` | Unique run identifier. Collectors assign via trace_id or session_id. |
+| `agent_name` | string | `"hermes"`, `"claude-code"`, `"codex"`, `"opencode"` | Which agent ran this. |
+| `collector` | string | `"hermes-trace-ingestor"`, `"claude-code-session-collector"` | Which collector produced this event. Enables audit trail. |
+| `started_at` | ISO 8601 string | `"2026-05-19T14:32:00Z"` | When the run began. |
+| `task_name` | string | `"Implement user authentication"` | What the agent was asked to do. Max 500 chars; first sentence only. |
+| `task_name` | string | (max 500 chars) | Task description (first sentence). |
+| `outcome` | enum string | `"success"`, `"failure"`, `"partial"`, `"unknown"` | Did the agent succeed? `success`: no errors, completed. `failure`: critical error. `partial`: partial success with non-critical errors. `unknown`: insufficient info. |
+
+### Optional Fields
+
+These fields MAY be absent or null. Collectors should populate them when available. Evaluators must handle missing values gracefully.
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `agent_version` | string | null | Agent version at run time. E.g., `"2.1.143"`. |
+| `provider` | string | null | AI provider: `"anthropic"`, `"openai"`, `"hermes"`, `"ollama"`, etc. |
+| `model` | string | null | Model ID. E.g., `"claude-opus-4-7"`, `"gpt-4-turbo"`. |
+| `repo` | string | null | Source code repo (git remote URL or local path). Used for run grouping. |
+| `session_id` | string | null | Unique session UUID from the agent. Links multiple runs to one session. |
+| `ended_at` | ISO 8601 string | null | When the run completed. If null, use current time. |
+| `tool_calls` | array of objects | `[]` | All tool invocations in sequence. See schema below. |
+| `files_touched` | array of objects | `[]` | All files read/written/deleted. See schema below. |
+| `artifacts` | array of objects | `[]` | Output artifacts (code, docs, reports). See schema below. |
+| `errors` | array of objects | `[]` | Exceptions and error signatures. See schema below. |
+| `metrics` | object | null | Aggregated execution metrics. See schema below. |
+| `eval_scores` | array of objects | `[]` | Scores from Phase 5 evaluation. Written post-run. See schema below. |
+| `improvement_candidates` | array of objects | `[]` | Proposed improvements (Phase 8+). |
+| `context` | object | `{}` | Catch-all for agent-specific or collector-specific fields. Never fails ingestion. |
+| `resolution` | string | null | How the run was resolved (if outcome == `"failure"`). Diagnostic text. |
+| `collector_version` | string | `"0.1.0"` | Version of the collector that produced this event. For forward compatibility. |
+
+---
+
+## Nested Object Schemas
+
+### `ToolCallRecord` (items in `tool_calls[]`)
+
+```json
+{
+  "id": "tool-call-uuid",
+  "name": "Read",
+  "input_summary": "Read /path/to/file.ts",
+  "duration_ms": 245,
+  "result_summary": "Returned 1240 chars",
+  "error": null
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | string | Unique ID for this tool call. E.g., UUID or sequential counter. |
+| `name` | string | Tool name. E.g., `"Read"`, `"Bash"`, `"Edit"`, `"Write"`, `"Grep"`, `"Agent"`. |
+| `input_summary` | string | First 200 chars of input. Omit secrets. |
+| `duration_ms` | integer | Execution time in milliseconds. Omit if not available. |
+| `result_summary` | string | First 200 chars of result/output. |
+| `error` | string or null | Error message if tool failed. Otherwise null. |
+
+### `FileTouchRecord` (items in `files_touched[]`)
+
+```json
+{
+  "path": "src/components/Button.tsx",
+  "action": "write",
+  "size_bytes": 2048
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `path` | string | File path. May be relative or absolute. |
+| `action` | string | One of: `"read"`, `"write"`, `"delete"`. |
+| `size_bytes` | integer or null | Final file size. Omit for deletes. |
+
+### `RunMetrics` (the `metrics` field)
+
+```json
+{
+  "input_tokens": 4200,
+  "output_tokens": 1850,
+  "cache_tokens": 512,
+  "latency_ms": 8500,
+  "cost_usd": 0.082,
+  "tool_call_count": 12
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `input_tokens` | integer or null | Tokens sent to model. |
+| `output_tokens` | integer or null | Tokens generated by model. |
+| `cache_tokens` | integer or null | Cached input tokens (prompt caching). |
+| `latency_ms` | integer or null | Total run duration in ms. |
+| `cost_usd` | float or null | Estimated cost in USD. |
+| `tool_call_count` | integer | Total tool calls made. Defaults to 0. |
+
+### `ErrorRecord` (items in `errors[]`)
+
+```json
+{
+  "signature": "TypeError: Cannot read property 'foo' of undefined",
+  "message": "TypeError: Cannot read property 'foo' of undefined at line 42",
+  "stack_excerpt": "at Object.<anonymous> (file.js:42:10)",
+  "count": 3
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `signature` | string | Error class + first line. Used for deduplication. E.g., `"TypeError: Cannot read property..."`. |
+| `message` | string | Full error message. |
+| `stack_excerpt` | string | First few stack frames (first 300 chars). |
+| `count` | integer | How many times this error occurred. Default 1. |
+
+### `EvalScore` (items in `eval_scores[]`)
+
+Written by Phase 5 evaluation engine. Not set by collectors.
+
+```json
+{
+  "scorer": "outcome_scorer",
+  "score": 1.0,
+  "passed": true,
+  "details": {
+    "outcome": "success",
+    "reason": "Run completed without errors"
+  }
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `scorer` | string | Name of the scorer that produced this. E.g., `"outcome_scorer"`, `"token_cost_scorer"`. |
+| `score` | float | Score in range [0.0, 1.0]. |
+| `passed` | boolean | Did this scorer report success? |
+| `details` | object | Scorer-specific metadata. Free-form. |
+
+### `Artifact` (items in `artifacts[]`)
+
+```json
+{
+  "path": "output/evolved_skill.md",
+  "type": "markdown",
+  "size_bytes": 4096
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `path` | string | Path to artifact. |
+| `type` | string | MIME-like type. E.g., `"markdown"`, `"json"`, `"python"`, `"typescript"`. |
+| `size_bytes` | integer | Size in bytes. |
+
+---
+
+## Backward Compatibility
+
+### Mapping from `TraceRecord` (Hermes legacy)
+
+The existing `TraceRecord` dataclass in `backend/promethean/models.py` maps to `CanonicalRun` as follows:
+
+| TraceRecord | CanonicalRun | Mapping rule |
+|-------------|--------------|--------------|
+| `trace_id` | `run_id` | Direct copy. |
+| `agent` | `agent_name` | Direct copy. |
+| `agent_version` | `agent_version` | Direct copy. |
+| `timestamp` | `started_at` | Direct copy (ISO 8601). |
+| — | `ended_at` | Set to `started_at` if missing. |
+| `task` | `task_name` | Direct copy. |
+| `outcome` | `outcome` | Direct copy (`"success"`, `"failure"`, `"partial"`). |
+| `error_signature` | `errors[0].signature` | Wrap in array. If empty, set `errors = []`. |
+| `context` | `context` | Direct copy (dict). |
+| `resolution` | `resolution` | Direct copy. |
+| — | `collector` | Set to `"hermes-trace-ingestor"` (constant). |
+| — | `provider` | Set to `"hermes"` (constant). |
+
+All other `CanonicalRun` fields default to null/empty if not present in `TraceRecord`.
+
+### Unknown Fields
+
+If a collector encounters a field not in this schema:
+- If it's non-sensitive: include it in `context{}`
+- If it's sensitive (API key, secret): omit it
+- Never reject the run due to unknown fields
+
+---
+
+## Version History
+
+### v0.1 (current)
+- Initial schema
+- Maps `TraceRecord` to `CanonicalRun`
+- Defines required fields: `run_id`, `agent_name`, `collector`, `started_at`, `task_name`, `outcome`
+- Defines optional fields for tools, files, metrics, errors, and scores
+
+### Future versions
+- v0.2: Add `parent_run_id` for nested agent calls
+- v0.3: Add `reproducibility_hash` for deterministic replay

package/.claude/worktrees/phase-2-mcp/specs/examples/run.jsonl

@@ -0,0 +1,3 @@
+{"run_id": "hermes-trace-001", "agent_name": "hermes", "collector": "hermes-trace-ingestor", "collector_version": "0.1.0", "started_at": "2026-05-19T14:32:00Z", "ended_at": "2026-05-19T14:35:42Z", "task_name": "Implement user authentication middleware", "outcome": "success", "agent_version": "2.1.143", "provider": "hermes", "model": null, "repo": "https://github.com/org/genoma.git", "session_id": null, "tool_calls": [{"id": "call-001", "name": "Read", "input_summary": "Read backend/main.py", "duration_ms": 145, "result_summary": "Returned 3240 chars", "error": null}, {"id": "call-002", "name": "Edit", "input_summary": "Add JWT middleware to FastAPI", "duration_ms": 320, "result_summary": "Edited 5 lines", "error": null}, {"id": "call-003", "name": "Bash", "input_summary": "pytest tests/test_auth.py", "duration_ms": 2100, "result_summary": "All 8 tests passed", "error": null}], "files_touched": [{"path": "backend/main.py", "action": "write", "size_bytes": 3240}, {"path": "backend/auth_middleware.py", "action": "write", "size_bytes": 1847}, {"path": "tests/test_auth.py", "action": "read", "size_bytes": 2156}], "artifacts": [{"path": "backend/auth_middleware.py", "type": "python", "size_bytes": 1847}], "errors": [], "metrics": {"input_tokens": 4200, "output_tokens": 1850, "cache_tokens": 512, "latency_ms": 8500, "cost_usd": 0.082, "tool_call_count": 3}, "eval_scores": [], "improvement_candidates": [], "context": {"skill_name": "auth-middleware", "commands": ["read backend/main.py", "edit backend/main.py", "bash pytest"], "files_touched": ["backend/main.py", "backend/auth_middleware.py", "tests/test_auth.py"]}, "resolution": null}
+{"run_id": "cc-session-e8f7a9d3", "agent_name": "claude-code", "collector": "claude-code-session-collector", "collector_version": "0.1.0", "started_at": "2026-05-19T11:22:00Z", "ended_at": "2026-05-19T11:28:15Z", "task_name": "Add dark mode toggle to React dashboard", "outcome": "success", "agent_version": "2.0.5", "provider": "anthropic", "model": "claude-opus-4-7", "repo": "main", "session_id": "e8f7a9d3-2bc1-4f8e-9a2b-5c7e9f1d3a4b", "tool_calls": [{"id": "tool-read-1", "name": "Read", "input_summary": "Read src/components/Sidebar.tsx", "duration_ms": 234, "result_summary": "Returned 1240 chars", "error": null}, {"id": "tool-edit-1", "name": "Edit", "input_summary": "Add theme state to Sidebar", "duration_ms": 412, "result_summary": "Edited 8 lines", "error": null}, {"id": "tool-write-1", "name": "Write", "input_summary": "Create src/hooks/useTheme.ts", "duration_ms": 178, "result_summary": "Created new file 745 bytes", "error": null}], "files_touched": [{"path": "src/components/Sidebar.tsx", "action": "write", "size_bytes": 1512}, {"path": "src/hooks/useTheme.ts", "action": "write", "size_bytes": 745}, {"path": "src/lib/theme.ts", "action": "write", "size_bytes": 892}], "artifacts": [{"path": "src/hooks/useTheme.ts", "type": "typescript", "size_bytes": 745}, {"path": "src/lib/theme.ts", "type": "typescript", "size_bytes": 892}], "errors": [], "metrics": {"input_tokens": 3450, "output_tokens": 1220, "cache_tokens": 340, "latency_ms": 5820, "cost_usd": 0.067, "tool_call_count": 3}, "eval_scores": [], "improvement_candidates": [], "context": {"cwd": "/Users/leandrothomas/Desktop/Projects/genoma", "gitBranch": "feature/dark-mode", "version": "2.0.5", "usage": {"input_tokens": 3450, "output_tokens": 1220, "cache_read_input_tokens": 340}}, "resolution": null}
+{"run_id": "unknown-run-abc123", "agent_name": "unknown-agent", "collector": "generic-json-ingestor", "started_at": "2026-05-19T10:00:00Z", "task_name": "Fix database query", "outcome": "partial"}