siesa-agents 2.1.78 → 2.1.80

package/siesa-agents/bmm/workflows/generate-project-context/workflow_ext.md

@@ -147,6 +147,58 @@ Once STEP 3 is complete and all variables (`selected_mode`, `output_file`, `feat
 
 ---
 
+# ============================================================================
+# SECTION 2.5: SIESA DISCOVERY EXTENSIONS (during step-01-discover.md)
+# ============================================================================
+
+> **Note:** These rules apply DURING `step-01-discover.md` execution, supplementing the standard discovery process.
+
+## Company Standards Loading
+
+After reading existing context and before presenting the discovery summary:
+
+- `{company_standards_path}` = `{project-root}/_siesa-agents/bmm/workflows/3-solutioning/create-architecture/data/company-standards`
+
+**If directory exists, load ALL markdown files:**
+- `technology-stack.md` — Stack corporativo (.NET 10, Vite 7+)
+- `database-conventions.md` — PostgreSQL naming conventions
+- `backend-standards.md` — Backend development patterns
+- `frontend-standards.md` — Frontend patterns + siesa-ui-kit rules
+- `architecture-patterns.md` — Architectural decision patterns
+- `technical-preferences-ux.md` — UX/UI preferences
+- `vite-config-standard.md` — Standard Vite configuration
+
+Company standards take **PRECEDENCE** over discovered patterns.
+
+Report: `✅ Estándares corporativos cargados: {count} archivos`
+
+## siesa-ui-kit Component Inventory
+
+🔴 **MANDATORY — Load siesa-ui-kit Component Inventory:**
+
+- Fetch the complete catalog from: `https://siesa-ui-kit.pages.dev/llms.txt`
+- Include the **full list of available siesa-ui-kit components** organized by category in the output document.
+- If unreachable: `⚠️ No se pudo cargar el catálogo de siesa-ui-kit. Incluir lista manualmente en el project context.`
+
+Report: `✅ Catálogo siesa-ui-kit cargado: {component_count} componentes disponibles`
+
+## Technology Stack — Vite over Next.js
+
+When discovering the frontend framework:
+- Identify **Vite** (`vite.config.ts`, `vite.config.js`) as the primary build tool.
+- Do NOT document Next.js-specific patterns unless the project explicitly uses Next.js.
+- In output examples, use Vite patterns (`src/main.tsx`, `routes/`, `stores/`) not Next.js patterns.
+
+## Critical P0 Rules to Extract and Document
+
+When loading company standards, specifically highlight in the output:
+- 🔴 **siesa-ui-kit requirement** — Must check siesa-ui-kit before creating any UI component
+- 🔴 **Spanish UI text** — All user-facing text must be in Spanish
+- 🔴 **DateTimeOffset** — Use DateTimeOffset not DateTime for time-aware fields
+- Technology versions (.NET 10, Vite 7+, TypeScript strict mode)
+
+---
+
 # ============================================================================
 # SECTION 3: MANDATORY RULE — PHASE COMMIT AT WORKFLOW END
 # ============================================================================

package/siesa-agents/bmm/workflows/testarch/framework/workflow_ext.md

@@ -0,0 +1,20 @@
+# MANDATORY RULE: TESTARCH FRAMEWORK — SIESA TECHNOLOGY EXTENSION
+
+**TRIGGER:** Every time the user initiates the `testarch-framework` workflow.
+
+---
+
+## 1. TECHNOLOGY STACK OVERRIDE
+
+When identifying the **project type** or **frontend framework** during test architecture initialization, apply the following Siesa-specific rule:
+
+### Vite instead of Next.js
+
+Siesa projects use **Vite** as the frontend build tool and dev server — NOT Next.js.
+
+When the base workflow mentions Next.js as an identifiable project type or example:
+- Treat **Vite** (with React, Vue, or plain TypeScript) as the primary frontend framework to identify and configure for.
+- Configuration files to look for: `vite.config.ts`, `vite.config.js`.
+- Do NOT generate test scaffolding targeting Next.js-specific APIs (e.g., `next/router`, App Router, Server Components).
+
+**Rationale:** Siesa's corporate technology stack mandates Vite 7+ for all new frontend projects. See `_siesa-agents/bmm/workflows/3-solutioning/create-architecture/data/company-standards/technology-stack.md` for full stack definition.

package/siesa-agents/bmm/workflows/workflow-status/init/workflow_ext.md

@@ -0,0 +1,194 @@
+# MANDATORY RULE: WORKFLOW-INIT — SIESA BASE REPOSITORY CLONING
+
+**TRIGGER:** Every time `workflow-init` is executed (`/sa-workflow-init`).
+
+**CONTEXT TO INJECT:** Load and hold these rules in memory. Apply them at the end of the workflow as described in Section 1.
+
+---
+
+## 1. Step 10: Clone Siesa Base Repositories
+
+This step executes **immediately after Step 9**, and **only if** the user confirmed creating the tracking file (answered "y"). If the user skipped Step 9 (answered "n"), skip this step entirely.
+
+### 1.1 Resolve project root
+
+Before running any command, determine the actual absolute path of `{project-root}`.
+This is the **current working directory** of the agent at runtime — the project folder where `_bmad/` and `_siesa-agents/` are installed.
+Use this resolved path in all subsequent commands. Do **not** pass the literal string `{project-root}` to the shell.
+
+### 1.2 Present menu to the user
+
+Use the **AskUserQuestion** tool to present the following options:
+
+> "To complete the project setup, I can clone the Siesa base repositories into the `apps/` folder. What would you like to clone?"
+>
+> **[1] Frontend + Backend** — Clone both base repositories.
+> **[2] Backend only** — Clone `BaseBackend` only.
+> **[3] Skip** — Do not clone any repository.
+
+### 1.3 Execution logic per selection
+
+**For options [1] and [2] — ensure `apps/` exists first:**
+
+```bash
+mkdir -p <resolved-project-root>/apps
+```
+
+**[1] Frontend + Backend:**
+
+Create base Architecture
+Copy the file `@_siesa-agents/resources/architecture/architecture-both.md ` to `{planning_artifacts}/architecture.md`.
+
+  - If the destination directory does not exist, create it first.
+  - Do not modify the file contents — copy as-is.
+  - After copying, confirm the file exists at the destination.
+
+Create base UX/UI specifications
+Copy the file `@_siesa-agents/resources/ux-ui/ux-design-specification.md` to `{planning_artifacts}/ux-design-specification.md.md`.
+
+  - If the destination directory does not exist, create it first.
+  - Do not modify the file contents — copy as-is.
+  - After copying, confirm the file exists at the destination.
+
+Check and clone Frontend:
+```bash
+# Only run if apps/Frontend does NOT exist
+git clone https://github.com/SiesaTeams/BaseFrontend.git <resolved-project-root>/apps/Frontend
+```
+
+Check and clone Backend:
+```bash
+# Only run if apps/Backend does NOT exist
+git clone https://github.com/SiesaTeams/BaseBackend.git <resolved-project-root>/apps/Backend
+```
+
+**[2] Backend only:**
+
+Create base Architecture
+Copy the file `@_siesa-agents/resources/architecture/architecture-single-backend.md ` to `{planning_artifacts}/architecture.md`.
+
+  - If the destination directory does not exist, create it first.
+  - Do not modify the file contents — copy as-is.
+  - After copying, confirm the file exists at the destination.
+
+Check and clone Backend:
+```bash
+git clone https://github.com/SiesaTeams/BaseBackend.git <resolved-project-root>/apps/Backend
+```
+
+**[3] Skip:** Do not execute any command. Proceed to the closing message.
+
+### 1.4 Pre-clone existence check
+
+Before running each `git clone`, verify whether the target directory already exists:
+
+- If `apps/Frontend` already exists → do **not** clone it; inform the user:
+  > "⚠️ `apps/Frontend` already exists. Skipping Frontend clone."
+
+- If `apps/Backend` already exists → do **not** clone it; inform the user:
+  > "⚠️ `apps/Backend` already exists. Skipping Backend clone."
+
+Continue with the remaining repo if only one was skipped.
+
+### 1.5 Error handling
+
+If a `git clone` command fails (network error, auth issue, etc.):
+
+1. Show the exact error output to the user.
+2. Ask: "❌ Could not clone `{repo-name}`. Would you like to retry? (y/n)"
+3. If "y": retry the same command once.
+4. If "n" or second failure: skip that repo and continue.
+
+### 1.6 Confirmation output
+
+After completing the cloning (success or partial), display a summary:
+
+```
+✅ Base repositories cloned into: <resolved-project-root>/apps/
+
+  Frontend  →  apps/Frontend   (https://github.com/SiesaTeams/BaseFrontend.git)
+  Backend   →  apps/Backend    (https://github.com/SiesaTeams/BaseBackend.git)
+
+Project structure is ready. Happy building! 🚀
+```
+
+Adapt the message if only one repo was cloned or if any were skipped.
+
+---
+
+## 2. Critical Rules
+
+1. **This step is mandatory in the flow** — once the menu is presented, the agent MUST act on the user's selection.
+2. **Do NOT modify Steps 1–9** of the base `workflow-init`. This extension only appends behavior at the end.
+3. **Always use the resolved absolute path** when running Bash commands. Never pass the literal string `{project-root}` to the shell — substitute it with the actual path first.
+4. **Each `git clone` runs as a single independent Bash tool call** using the full absolute target path as the destination argument — do not rely on `cd` to set context across calls.
+5. **Condition gate** — if the user did not confirm Step 9 (answered "n"), this entire step is skipped without presenting the menu.
+
+---
+
+## 3. MANDATORY RULE — PHASE BRANCH CREATION AT WORKFLOW START
+
+**TRIGGER:** Immediately when the user initiates this workflow (e.g., `/sa-workflow-init`).
+
+**CRITICAL INSTRUCTION:** Before executing any workflow step, you MUST invoke the `generate-commits-by-phase` skill to create the Phase 1 discovery branch.
+
+### EXECUTION STEPS (PERFORM THESE ACTIONS NOW, BEFORE ANYTHING ELSE)
+
+**STEP 1: INVOKE THE SKILL — CREATE PHASE 1 BRANCH**
+
+Run the skill `generate-commits-by-phase` with **Operation A: Create Phase Branch** for **Phase 1 (discovery)**:
+
+```bash
+node _siesa-agents/scripts/phases/phase1.js
+```
+
+- If the `discovery` branch already exists, the script will report it — continue normally.
+- If it is created successfully, confirm to the user and proceed.
+
+**STEP 2: CONFIRM AND CONTINUE**
+
+Output to the user:
+> `✅ Phase 1 (discovery) branch ready. Proceeding with workflow-init...`
+
+**DO NOT proceed to the workflow steps until this rule is fully executed.**
+
+---
+
+## 4. MANDATORY RULE — PHASE COMMIT AT WORKFLOW END
+
+**TRIGGER:** Immediately after all workflow steps complete (including Section 1 — repository cloning).
+
+**CRITICAL INSTRUCTION:** As the final action of this workflow, you MUST invoke the `generate-commits-by-phase` skill to commit all changes for Phase 1.
+
+### EXECUTION STEPS (PERFORM THESE ACTIONS AT THE END)
+
+**STEP 1: INSPECT CHANGES**
+
+Before committing, inspect the repository state:
+
+1. Run `git status --short` to identify which files were created or modified.
+2. Run `git diff --stat` to understand the scope of changes.
+
+**STEP 2: GENERATE COMMIT MESSAGE**
+
+Build a concise commit message using the format:
+`[Phase 1 - Discovery] <brief description of what was produced>`
+
+**Example:** `[Phase 1 - Discovery] initialize project structure and clone base repositories`
+
+Write the message in the same language used throughout the conversation.
+
+**STEP 3: INVOKE THE SKILL — COMMIT PHASE 1 CHANGES**
+
+Run the skill `generate-commits-by-phase` with **Operation B: Commit All Changes** for **Phase 1 (discovery)**:
+
+```bash
+node _siesa-agents/scripts/phases/phase1.js --commit "<generated commit message>"
+```
+
+**STEP 4: CONFIRM COMPLETION**
+
+Output to the user:
+> `✅ Project initialization changes committed to Phase 1 (discovery) branch.`
+
+**This is the LAST action of the workflow. Do not execute any further steps after this commit.**

package/siesa-agents/observability/README.md

@@ -1,16 +1,166 @@
 # Observability Module
 
-Instrumentación de los workflows BMAD para medir el tiempo real por historia de usuario.
+Instrumentación de los workflows BMAD (`create-story`, `dev-story`, `code-review`) para medir **tiempo y tokens** consumidos por historia de usuario. Envía eventos OTLP/HTTP al gateway de GCP.
 
-## Qué hace
+## Componentes
 
-Cada workflow (`create-story`, `dev-story`, `code-review`) emite **3 eventos** a Loki via el script `sa-emit.js`:
+| Archivo | Rol |
+|---|---|
+| `sa-emit.js` | Emite eventos OTLP/HTTP. Lo invocan los `workflow_ext.md` desde Bash en pasos puntuales |
+| `sa-session.js` | Hook `SessionStart`. Persiste `session_id` y `transcript_path` por PID de `claude.exe` |
+| `sa-clean.js` | Script de limpieza manual. Usado por la skill `/clean-observability` |
+| `sa-pid.js` | Helper compartido: PID-walk + listado de `claude.exe` vivos |
+
+Cero dependencias externas — solo módulos built-in de Node (`fs`, `path`, `os`, `child_process`).
+
+## Flujo end-to-end
+
+```
+[Arranca CC]
+   └─ SessionStart hook → sa-session.js
+        └─ Guarda ~/.claude/observability/session-<claude_pid>.json
+             { session_id, transcript_path, cwd, claude_pid }
+
+[Ingeniero ejecuta /create-story | /dev-story | /code-review]
+   └─ workflow_ext.md ejecuta:
+        node sa-emit.js --event workflow.started --story X --phase Y
+            ├─ PID-walk: encuentra claude.exe ancestro
+            ├─ Lee session-<pid>.json para obtener session_id y transcript_path
+            └─ Emite OTLP log con session_id
+
+[Modelo trabaja durante N turnos — sin instrumentación adicional]
+
+[Workflow llega a su último step]
+   └─ workflow_ext.md ejecuta:
+        node sa-emit.js --event workflow.finished --story X --phase Y
+            ├─ Lee start_ms del state file
+            ├─ Lee transcript_path → suma usage.* de mensajes con ts ≥ start_ms
+            └─ Emite OTLP log con duration_ms + tokens_*
+
+[Semanal/cuando se quiera]
+   └─ /clean-observability → sa-clean.js --dry-run → confirma → --apply
+```
+
+## Eventos por workflow
+
+| Workflow | Eventos emitidos | Cantidad |
+|---|---|---|
+| `create-story` | `workflow.started` → `status.changed`(backlog→ready-for-dev) → `workflow.finished` | 3 |
+| `dev-story` | `workflow.started` → `status.changed`(in-progress→review) → `workflow.finished` | 3 |
+| `code-review` (sin fix) | `workflow.started` → `status.changed` → `workflow.finished` | 3 |
+| `code-review` (con fix) | `workflow.started` → `fix.started` → `fix.finished` → `status.changed` → `workflow.finished` | 5 |
+
+Para code-review, `fix.*` aísla el slice del fix (tokens del fix solamente). `workflow.finished` incluye TODO (análisis + fix + sync + commit).
+
+---
+
+## Inventario completo de campos enviados a GCP
+
+### 1. Metadata del log record (presente en todos los eventos)
+
+| Campo | Valor | Notas |
+|---|---|---|
+| `timeUnixNano` | Timestamp del evento (ns) | Puede backdate con `--timestamp-offset-ms` |
+| `observedTimeUnixNano` | Mismo que `timeUnixNano` | |
+| `severityNumber` | `9` (INFO) | |
+| `severityText` | `"INFO"` | |
+| `body.stringValue` | Resumen legible (ej: `workflow.finished \| story=1-1-foo phase=create-story project=... engineer=... session=...`) | Para grep rápido |
+
+### 2. Resource attributes (constantes por proceso)
+
+| Campo | Origen | Ejemplo |
+|---|---|---|
+| `service.name` | Hardcoded | `"bmad"` |
+| `project_id` | Cadena de resolución (ver "Resolución de `project_id`" abajo) | `"pos-pdv"` o `"SiesaTeams/Siesa-Agents"` |
+| `engineer` | `git config user.name` (o `--engineer`) | `"Guillermo Augusto Duran Boneth"` |
+
+#### Resolución de `project_id`
+
+`sa-emit.js` resuelve el `project_id` en este orden (la primera fuente que devuelve un valor gana):
+
+```
+1. --project-id "<x>"                 ← arg CLI explícito (máxima prioridad)
+2. .siesa-project en el árbol padre   ← override por proyecto lógico
+3. git remote get-url origin          ← fallback automático (comportamiento histórico)
+4. "unknown"                          ← si nada resolvió
+```
+
+**`.siesa-project` (opcional pero recomendado para proyectos con sub-repos)**
+
+Cuando un proyecto lógico tiene varios sub-repos clonados (típicamente `docs/`, `apps/backend/`, `apps/frontend/`), cada uno tiene un `git remote` distinto. Eso fragmenta el `project_id` en GCP y la misma épica termina contada N veces.
+
+Solución: crear un archivo `.siesa-project` en la **carpeta padre** que contiene los sub-repos. Una sola línea con el nombre del proyecto lógico:
+
+```
+comercial/                       ← carpeta padre (no es repo git)
+├── .siesa-project               ← una línea: "pos-pdv"
+├── docs/                        ← clonado de business-pos-docs-pdv
+└── apps/
+    ├── backend/                 ← clonado de business-pos-backend-pdv
+    └── frontend/                ← clonado de business-pos-frontend-pdv
+```
+
+`sa-emit.js` camina hacia arriba desde el `cwd`, encuentra el `.siesa-project`, y reporta `project_id=pos-pdv` sin importar si el workflow se ejecutó desde `docs/`, `apps/backend/` o `apps/frontend/`.
+
+**Convención sugerida del archivo:** una sola línea, slug en minúsculas con guiones (`pos-pdv`, `pos-tomapedido`, `comercial`). Sin JSON, sin YAML.
+
+Proyectos sin sub-repos (un único `git remote` cubre todo) no necesitan `.siesa-project` — el fallback al git remote sigue funcionando.
+
+### 3. Scope
+
+| Campo | Valor |
+|---|---|
+| `scope.name` | `"bmad.observability"` |
+
+### 4. Atributos siempre presentes en cada evento
+
+| Campo | Valores posibles |
+|---|---|
+| `event` | `workflow.started`, `workflow.finished`, `status.changed`, `fix.started`, `fix.finished` |
+| `story_id` | ej. `"1-1-user-auth"` |
+| `epic_id` | ej. `"1"` (derivado del prefijo de story_id) |
+| `phase` | `create-story`, `dev-story`, `code-review` |
+
+### 5. Atributos condicionales
 
-1. `workflow.started` — al inicio del workflow, después de identificar la historia
-2. `status.changed` — cuando cambia el estado en `sprint-status.yaml`
-3. `workflow.finished` — al finalizar el workflow (incluye `duration_ms`)
+| Campo | Cuándo aparece | Valores |
+|---|---|---|
+| `session_id` | Si PID-walk encontró `claude.exe` padre y resolvió la sesión | UUID de la sesión CC |
+| `from` | Solo en `status.changed` | `backlog`, `ready-for-dev`, `in-progress`, `review` |
+| `to` | Solo en `status.changed` | `ready-for-dev`, `in-progress`, `review`, `done` |
+| `fix_option` | Solo en `fix.started` y `fix.finished` | `auto_fix`, `action_items`, `show_details` |
+| `duration_ms` | Solo en `workflow.finished` y `fix.finished` | int — diferencia con el `*.started` correspondiente |
+
+### 6. Atributos de tokens — solo en `workflow.finished` y `fix.finished`
+
+(Y solo si se resolvió `session_id` y se pudo leer el `transcript_path` del JSONL.)
+
+| Campo | Significado |
+|---|---|
+| `tokens_input` | Tokens de input NUEVOS sumados entre `started_at` y ahora (no cuenta cache) |
+| `tokens_output` | Tokens generados por el modelo en ese slice |
+| `tokens_cache_read` | Tokens leídos de cache (cuestan ~10% pero se contabilizan) |
+| `tokens_cache_creation` | Tokens escritos al cache |
+| `tokens_total` | Suma de los 4 anteriores — costo bruto facturable |
+| `models_used` | Lista coma-separada de modelos usados (ej. `claude-opus-4-7,claude-sonnet-4-6`) |
 
-## Script: `sa-emit.js`
+### Cardinalidad total
+
+Hasta **23 campos por evento** dependiendo de su tipo. Inventario en formato programático:
+
+```
+metadata:    timeUnixNano, observedTimeUnixNano, severityNumber, severityText, body
+resource:    service.name, project_id, engineer
+scope:       scope.name
+always:      event, story_id, epic_id, phase
+conditional: session_id, from, to, fix_option, duration_ms
+tokens:      tokens_input, tokens_output, tokens_cache_read,
+             tokens_cache_creation, tokens_total, models_used
+```
+
+---
+
+## CLI de `sa-emit.js`
 
 ```bash
 # Inicio de workflow
@@ -19,63 +169,124 @@ node sa-emit.js --event workflow.started --story "1-1-user-auth" --phase "create
 # Transición de estado
 node sa-emit.js --event status.changed --story "1-1-user-auth" --phase "create-story" --from "backlog" --to "ready-for-dev"
 
-# Fin de workflow (calcula duration_ms automáticamente)
+# Fin de workflow (calcula duration_ms + tokens automáticamente)
 node sa-emit.js --event workflow.finished --story "1-1-user-auth" --phase "create-story"
+
+# Fix dentro de code-review
+node sa-emit.js --event fix.started  --story "1-1-user-auth" --phase "code-review" --fix-option auto_fix
+node sa-emit.js --event fix.finished --story "1-1-user-auth" --phase "code-review" --fix-option auto_fix
 ```
 
 ### Parámetros
 
-| Parámetro       | Requerido          | Valores |
+| Parámetro | Requerido | Valores |
 |---|---|---|
-| `--event`       | Sí                 | `workflow.started`, `workflow.finished`, `status.changed`, `fix.started`, `fix.finished` |
-| `--story`       | Sí                 | Story key (e.g. `1-1-user-auth`) |
-| `--phase`       | Sí                 | `create-story`, `dev-story`, `code-review` |
-| `--from`        | Solo en transition | Estado origen (e.g. `backlog`) |
-| `--to`          | Solo en transition | Estado destino (e.g. `ready-for-dev`) |
-| `--fix-option`  | Solo en fix.*      | `auto_fix`, `action_items`, `show_details` |
+| `--event` | Sí | `workflow.started`, `workflow.finished`, `status.changed`, `fix.started`, `fix.finished` |
+| `--story` | Sí | Story key (ej. `1-1-user-auth`) |
+| `--phase` | Sí | `create-story`, `dev-story`, `code-review` |
+| `--from` | Solo en `status.changed` | Estado origen |
+| `--to` | Solo en `status.changed` | Estado destino |
+| `--fix-option` | Solo en `fix.*` | `auto_fix`, `action_items`, `show_details` |
+| `--engineer` | Opcional | Override del `git config user.name` |
+| `--project-id` | Opcional | Override del `project_id` derivado de git remote |
+| `--timestamp-offset-ms` | Opcional | Backdate del evento en ms |
 
-### Configuración
+---
 
-| Variable de entorno | Default | Descripción |
-|---|---|---|
-| `SA_OTLP_ENDPOINT` | `http://localhost:4318` | URL base del OTel collector (OTLP HTTP) |
+## Configuración
+
+### Resolución del endpoint OTLP
 
-### Fallback
+`sa-emit.js` resuelve el endpoint OTLP siguiendo este orden:
 
-Si el OTel collector no está disponible, los eventos se guardan en `~/.claude/observability/buffer/events.jsonl` para reenvío manual.
+```
+1. process.cwd()/.env                          ← override por proyecto (raro)
+2. ~/.claude/observability/.env                ← DEFAULT machine-wide (el común)
+3. process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT ← red de seguridad gratis
+4. process.env.OTEL_EXPORTER_OTLP_ENDPOINT     ← idem
+5. ERROR + buffer                              ← fail-fast con mensaje útil
+```
+
+Lo mismo aplica para los headers (`SA_OTLP_HEADERS` → `OTEL_EXPORTER_OTLP_HEADERS`).
+
+### Onboarding del equipo (una sola vez por PC)
+
+```powershell
+$envDir = "$HOME\.claude\observability"
+New-Item -ItemType Directory -Force $envDir | Out-Null
+@"
+SA_OTLP_ENDPOINT=https://platform-otel-collector-gateway-1bo4ifqc.ue.gateway.dev
+SA_OTLP_HEADERS=x-api-key=<api-key>
+"@ | Set-Content "$envDir\.env"
+```
+
+Después de esto, los workflows funcionan desde cualquier repo donde el paquete esté instalado.
+
+### Hook `SessionStart`
 
-## Estructura del evento
+Debe estar configurado en `.claude/settings.local.json` (dev) o `claude/settings.local.json` (npm):
 
 ```json
 {
-  "event": "workflow.finished",
-  "story_id": "1-1-user-auth",
-  "epic_id": "1",
-  "phase": "create-story",
-  "duration_ms": 1140000
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "node \"${CLAUDE_PROJECT_DIR}/_siesa-agents/observability/scripts/sa-session.js\""
+      }]
+    }]
+  }
 }
 ```
 
-## Queries en Grafana (Loki)
+Sin este hook, `sa-emit.js` puede emitir eventos pero **no podrá resolver `session_id` ni sumar tokens**. Los `*.finished` solo tendrán `duration_ms`.
 
-```logql
-# Timeline de una historia
-{job="bmad"} | json | story_id="1-1-user-auth"
+### Fallback / buffer
 
-# Duración de workflows finalizados
-{job="bmad"} | json | event="workflow.finished"
+Si el gateway no responde o no hay endpoint configurado, los eventos se guardan en `~/.claude/observability/buffer/events.jsonl`. El workflow nunca se bloquea. La rotación se hace vía `/clean-observability --rotate-buffer` cuando el buffer supera 5 MB.
 
-# Historias completadas (última semana)
-count_over_time({job="bmad"} | json | event="status.changed" | to="done" [7d])
+---
+
+## Queries útiles en GCP (Cloud Logging)
 
-# Interacciones del usuario en un workflow (telemetría nativa)
-{service_name="claude-code"} | json | event_name="user_prompt" | session_id="<id>"
 ```
+# Toda la actividad de una historia (timeline)
+logName="projects/<project>/logs/claude-code-telemetry"
+AND labels.story_id="1-1-user-auth"
 
-## Transiciones por workflow
+# Workflows terminados con duración y tokens
+logName="projects/<project>/logs/claude-code-telemetry"
+AND labels.event="workflow.finished"
 
-| Workflow | Transiciones emitidas |
-|---|---|
-| `create-story` | `backlog → ready-for-dev` |
-| `dev-story` | `ready-for-dev → in-progress`, `in-progress → review` |
-| `code-review` | `review → done` o `review → in-progress` (rework) |
+# Costo por ingeniero (suma de tokens en la última semana)
+logName="projects/<project>/logs/claude-code-telemetry"
+AND labels.event="workflow.finished"
+AND labels.engineer="Guillermo Augusto Duran Boneth"
+AND timestamp >= "2026-04-29T00:00:00Z"
+
+# Fix de code-review automatizados (frecuencia de auto_fix vs action_items)
+logName="projects/<project>/logs/claude-code-telemetry"
+AND labels.event="fix.finished"
+AND labels.fix_option="auto_fix"
+
+# Correlación tokens del análisis vs tokens del fix
+# tokens_analisis = workflow.finished.tokens_total - fix.finished.tokens_total
+# tokens_fix       = fix.finished.tokens_total
+```
+
+---
+
+## Cleanup
+
+La skill `/clean-observability` (en `.claude/skills/clean-observability/`) ejecuta `sa-clean.js`:
+
+- Lista los `claude.exe` vivos en la máquina.
+- Para cada archivo de estado (`session-*.json`, `session-id-*.json`, `wf-*.json`, `fix-*.json`):
+  - Si su `claude_pid` registrado pertenece a un proceso vivo → conserva.
+  - Si no → propone borrar.
+- Confirma con el usuario antes de aplicar.
+- Opcional: rota `buffer/events.jsonl` si supera 5 MB.
+
+Es **paralelo-safe**: nunca borra archivos de sesiones activas, sin importar en qué consola se ejecute.
+
+Frecuencia recomendada: semanal o cuando el directorio se vea cargado.

package/siesa-agents/observability/scripts/sa-emit.js

@@ -134,15 +134,40 @@ const stateDir = path.join(os.homedir(), '.claude', 'observability')
 const epicIdMatch = story.match(/^(\d+)-/)
 const epicId      = epicIdMatch ? epicIdMatch[1] : 'unknown'
 
+function findSiesaProject(startDir) {
+  // Walk up from startDir looking for a `.siesa-project` file. Returns its first non-empty
+  // line trimmed, or null. Lets a parent dir override the git-remote-derived project_id —
+  // useful when several sub-repos (docs/backend/frontend) belong to the same logical project.
+  let cur = path.resolve(startDir)
+  for (let i = 0; i < 40; i++) {
+    const candidate = path.join(cur, '.siesa-project')
+    if (fs.existsSync(candidate)) {
+      try {
+        const first = fs.readFileSync(candidate, 'utf8').split(/\r?\n/)[0].trim()
+        if (first) return first
+      } catch (_) {}
+    }
+    const parent = path.dirname(cur)
+    if (parent === cur) return null   // hit filesystem root
+    cur = parent
+  }
+  return null
+}
+
 let projectId = 'unknown'
 if (projectIdOverride) {
   projectId = projectIdOverride
 } else {
-  try {
-    const remoteUrl = execSync('git remote get-url origin', { encoding: 'utf8' }).trim()
-    const m = remoteUrl.match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/)
-    if (m) projectId = m[1]
-  } catch (_) {}
+  const fromSiesaProject = findSiesaProject(process.cwd())
+  if (fromSiesaProject) {
+    projectId = fromSiesaProject
+  } else {
+    try {
+      const remoteUrl = execSync('git remote get-url origin', { encoding: 'utf8' }).trim()
+      const m = remoteUrl.match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/)
+      if (m) projectId = m[1]
+    } catch (_) {}
+  }
 }
 
 let engineer = 'unknown'