siesa-agents 2.1.72 → 2.1.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.72",
+  "version": "2.1.73",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {

package/siesa-agents/bmm/workflows/4-implementation/code-review/workflow_ext.md

@@ -139,3 +139,83 @@ Update frontmatter of `{outputFile}`: `stepsCompleted: [1, 2, 3, 4, 5, 6]`
 Output: `✅ Jira sync complete. Proceeding to commit...`
 
 Then **immediately load, read, and execute step-07-commit-push.md** — no menu, no waiting for user input.
+
+# MANDATORY RULE: OBSERVABILITY EVENTS
+
+**TRIGGER:** Every time the code-review workflow is executed.
+
+**PURPOSE:** Emit lifecycle events to measure workflow duration per story. Events are sent to Loki for observability dashboards.
+
+**SCRIPT PATH:** `{project_root}/_siesa-agents/observability/scripts/sa-emit.js`
+
+## 4. After step-01 identifies the story (before proceeding to step-02)
+
+Once `{{story_key}}` has been determined in step-01-load-story, and BEFORE proceeding to step-02, execute via Bash:
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event workflow.started --story "{{story_key}}" --phase code-review
+```
+
+## 4.5. In step-04, when the user selects a fix option (before executing it)
+
+When the user selects one of the fix options **[1], [2], or [3]**, emit `fix.started` BEFORE executing the option, then emit `fix.finished` AFTER it completes:
+
+**When user selects [1] Fix automatically:**
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event fix.started --story "{{story_key}}" --phase code-review --fix-option auto_fix
+```
+*(execute the fix)* then:
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event fix.finished --story "{{story_key}}" --phase code-review --fix-option auto_fix
+```
+
+**When user selects [2] Create Action Items:**
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event fix.started --story "{{story_key}}" --phase code-review --fix-option action_items
+```
+*(create the action items)* then:
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event fix.finished --story "{{story_key}}" --phase code-review --fix-option action_items
+```
+
+**When user selects [3] Show Details:**
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event fix.started --story "{{story_key}}" --phase code-review --fix-option show_details
+```
+*(show the details)* then:
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event fix.finished --story "{{story_key}}" --phase code-review --fix-option show_details
+```
+
+## 5. In step-05, after updating sprint-status.yaml
+
+After step-05-sync-sprint updates `sprint-status.yaml`, emit the transition based on the actual new status determined by the review outcome:
+
+**If the review PASSED (story transitions to `done`):**
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event status.changed --story "{{story_key}}" --phase code-review --from review --to done
+```
+
+**If the review FAILED and story goes back to `in-progress` (rework):**
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event status.changed --story "{{story_key}}" --phase code-review --from review --to in-progress
+```
+
+## 6. In step-07, at the very end of the workflow (after commit/push completes)
+
+At the end of step-07-commit-push, after the final output, execute via Bash:
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event workflow.finished --story "{{story_key}}" --phase code-review
+```
+
+## Observability execution rules
+
+- If any `sa-emit` call fails, log the error and **continue the workflow normally**. Observability must never block the workflow.
+- Use the exact `{{story_key}}` value as resolved in step-01 (e.g., `1-1-user-authentication`).
+- Do NOT wait for user confirmation to execute these commands — they are silent background operations.

package/siesa-agents/bmm/workflows/4-implementation/create-story/workflow_ext.md

@@ -42,4 +42,38 @@ The following rules must be kept in memory and applied at the appropriate moment
 Sub-agents **must NOT be used** when the code review workflow is invoked directly (e.g., `/create-story`). Sub-agents are only permitted when the workflow is triggered as part of **quick-dev** (e.g., `/quick-dev`).
 
 - If invoked directly → follow the standard sequential workflow steps without spawning any sub-agents.
-- If invoked from quick-dev → sub-agents may be used as defined by the quick-dev orchestration.
+- If invoked from quick-dev → sub-agents may be used as defined by the quick-dev orchestration.
+
+# MANDATORY RULE: OBSERVABILITY EVENTS
+
+**TRIGGER:** Every time the create-story workflow is executed.
+
+**PURPOSE:** Emit lifecycle events to measure workflow duration per story. Events are sent to Loki for observability dashboards.
+
+**SCRIPT PATH:** `{project_root}/_siesa-agents/observability/scripts/sa-emit.js`
+
+## 2. After step-01 identifies the story (before presenting the menu)
+
+Once `{{story_key}}` has been determined (sections 1-3 of step-01), and BEFORE presenting the menu options (section 4), execute via Bash:
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event workflow.started --story "{{story_key}}" --phase create-story
+```
+
+## 3. In step-06, after updating sprint-status.yaml (before the Final Report)
+
+After the sprint-status.yaml update (section 1) completes and BEFORE the Final Report (section 3), execute these two commands in sequence via Bash:
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event status.changed --story "{{story_key}}" --phase create-story --from backlog --to ready-for-dev
+```
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event workflow.finished --story "{{story_key}}" --phase create-story
+```
+
+## Observability execution rules
+
+- If any `sa-emit` call fails, log the error and **continue the workflow normally**. Observability must never block the workflow.
+- Use the exact `{{story_key}}` value as resolved in step-01 (e.g., `1-1-user-authentication`).
+- Do NOT wait for user confirmation to execute these commands — they are silent background operations.

package/siesa-agents/bmm/workflows/4-implementation/dev-story/workflow_ext.md

@@ -106,4 +106,38 @@ Example: `develop-legacy-erp-nomina-gaduranb-rq1234-nueva-interfaz`
 Sub-agents **must NOT be used** when the code review workflow is invoked directly (e.g., `/dev-story`). Sub-agents are only permitted when the workflow is triggered as part of **quick-dev** (e.g., `/quick-dev`).
 
 - If invoked directly → follow the standard sequential workflow steps without spawning any sub-agents.
-- If invoked from quick-dev → sub-agents may be used as defined by the quick-dev orchestration.
+- If invoked from quick-dev → sub-agents may be used as defined by the quick-dev orchestration.
+
+# MANDATORY RULE: OBSERVABILITY EVENTS
+
+**TRIGGER:** Every time the dev-story workflow is executed.
+
+**PURPOSE:** Emit lifecycle events to measure workflow duration per story. Events are sent to Loki for observability dashboards.
+
+**SCRIPT PATH:** `{project_root}/_siesa-agents/observability/scripts/sa-emit.js`
+
+## 5. After step-01 identifies the story (before presenting the menu)
+
+Once `{{story_key}}` has been determined in step-01-find-story, and BEFORE presenting the menu or proceeding to step-02, execute via Bash:
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event workflow.started --story "{{story_key}}" --phase dev-story
+```
+
+## 6. In step-11, after marking the story as review in sprint-status.yaml
+
+After step-11-mark-review updates `sprint-status.yaml` (`in-progress → review`), and BEFORE proceeding to step-12, execute these two commands in sequence via Bash:
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event status.changed --story "{{story_key}}" --phase dev-story --from in-progress --to review
+```
+
+```bash
+node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event workflow.finished --story "{{story_key}}" --phase dev-story
+```
+
+## Observability execution rules
+
+- If any `sa-emit` call fails, log the error and **continue the workflow normally**. Observability must never block the workflow.
+- Use the exact `{{story_key}}` value as resolved in step-01 (e.g., `1-1-user-authentication`).
+- Do NOT wait for user confirmation to execute these commands — they are silent background operations.

package/siesa-agents/observability/README.md

@@ -0,0 +1,81 @@
+# Observability Module
+
+Instrumentación de los workflows BMAD para medir el tiempo real por historia de usuario.
+
+## Qué hace
+
+Cada workflow (`create-story`, `dev-story`, `code-review`) emite **3 eventos** a Loki via el script `sa-emit.js`:
+
+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`)
+
+## Script: `sa-emit.js`
+
+```bash
+# Inicio de workflow
+node sa-emit.js --event workflow.started --story "1-1-user-auth" --phase "create-story"
+
+# 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)
+node sa-emit.js --event workflow.finished --story "1-1-user-auth" --phase "create-story"
+```
+
+### Parámetros
+
+| 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` |
+
+### Configuración
+
+| Variable de entorno | Default | Descripción |
+|---|---|---|
+| `SA_OTLP_ENDPOINT` | `http://localhost:4318` | URL base del OTel collector (OTLP HTTP) |
+
+### Fallback
+
+Si el OTel collector no está disponible, los eventos se guardan en `~/.claude/observability/buffer/events.jsonl` para reenvío manual.
+
+## Estructura del evento
+
+```json
+{
+  "event": "workflow.finished",
+  "story_id": "1-1-user-auth",
+  "epic_id": "1",
+  "phase": "create-story",
+  "duration_ms": 1140000
+}
+```
+
+## Queries en Grafana (Loki)
+
+```logql
+# Timeline de una historia
+{job="bmad"} | json | story_id="1-1-user-auth"
+
+# Duración de workflows finalizados
+{job="bmad"} | json | event="workflow.finished"
+
+# Historias completadas (última semana)
+count_over_time({job="bmad"} | json | event="status.changed" | to="done" [7d])
+
+# Interacciones del usuario en un workflow (telemetría nativa)
+{service_name="claude-code"} | json | event_name="user_prompt" | session_id="<id>"
+```
+
+## Transiciones por workflow
+
+| 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) |

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

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// sa-emit.js — Emit BMAD workflow lifecycle events via OTLP to the OTel collector
+//
+// Usage:
+//   node sa-emit.js --event workflow.started  --story "1-1-user-auth" --phase "create-story"
+//   node sa-emit.js --event status.changed    --story "1-1-user-auth" --phase "create-story" --from "backlog" --to "ready-for-dev"
+//   node sa-emit.js --event workflow.finished --story "1-1-user-auth" --phase "create-story"
+//   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"
+//
+// Optional overrides (useful for simulations / multi-engineer scenarios):
+//   --engineer "<name>"          Override git config user.name for this emit
+//   --project-id "<name>"        Override the git-remote-derived project id
+//   --timestamp-offset-ms <ms>   Subtract ms from the event timestamp (backdate the log record)
+//
+// Environment:
+//   SA_OTLP_ENDPOINT — OTel collector HTTP endpoint (default: http://localhost:4318)
+//   SA_OTLP_HEADERS  — Additional headers, comma-separated: "Authorization=Bearer xxx,X-Other=yyy"
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { execSync } = require('child_process')
+
+const VALID_EVENTS      = ['workflow.started', 'workflow.finished', 'status.changed', 'fix.started', 'fix.finished']
+const VALID_PHASES      = ['create-story', 'dev-story', 'code-review']
+const VALID_FIX_OPTIONS = ['auto_fix', 'action_items', 'show_details']
+
+function parseArgs(argv) {
+  const result = {}
+  let i = 0
+  while (i < argv.length) {
+    const arg = argv[i]
+    if (arg.startsWith('--')) {
+      const key  = arg.slice(2)
+      const next = argv[i + 1]
+      if (next !== undefined && !next.startsWith('--')) {
+        result[key] = next
+        i += 2
+      } else {
+        result[key] = true
+        i += 1
+      }
+    } else {
+      i += 1
+    }
+  }
+  return result
+}
+
+const args      = parseArgs(process.argv.slice(2))
+const event     = args['event']
+const story     = args['story']
+const phase     = args['phase']
+const from      = args['from']
+const to        = args['to']
+let   fixOption = args['fix-option']
+const engineerOverride   = args['engineer']
+const projectIdOverride  = args['project-id']
+const timestampOffsetMs  = args['timestamp-offset-ms'] ? parseInt(args['timestamp-offset-ms'], 10) : 0
+
+if (!event || !story || !phase) {
+  console.error('Error: --event, --story, and --phase are required')
+  console.error('Usage: node sa-emit.js --event <event> --story <story> --phase <phase> [--from <from>] [--to <to>] [--fix-option <opt>]')
+  process.exit(1)
+}
+if (!VALID_EVENTS.includes(event)) {
+  console.error(`Error: --event must be one of: ${VALID_EVENTS.join(', ')}`)
+  process.exit(1)
+}
+if (!VALID_PHASES.includes(phase)) {
+  console.error(`Error: --phase must be one of: ${VALID_PHASES.join(', ')}`)
+  process.exit(1)
+}
+if (fixOption && !VALID_FIX_OPTIONS.includes(fixOption)) {
+  console.error(`Error: --fix-option must be one of: ${VALID_FIX_OPTIONS.join(', ')}`)
+  process.exit(1)
+}
+
+const otlpEndpoint = process.env.SA_OTLP_ENDPOINT || 'http://localhost:4318'
+const stateDir     = path.join(os.homedir(), '.claude', 'observability')
+
+const epicIdMatch = story.match(/^(\d+)-/)
+const epicId      = epicIdMatch ? epicIdMatch[1] : 'unknown'
+
+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 (_) {}
+}
+
+let engineer = 'unknown'
+if (engineerOverride) {
+  engineer = engineerOverride
+} else {
+  try {
+    const gitUser = execSync('git config user.name', { encoding: 'utf8' }).trim()
+    if (gitUser) engineer = gitUser
+  } catch (_) {}
+}
+
+const nowMs       = Date.now()
+const eventTimeMs = nowMs - (Number.isFinite(timestampOffsetMs) ? timestampOffsetMs : 0)
+const tsNano      = `${eventTimeMs}000000`
+
+const safeKey   = story.replace(/[^a-zA-Z0-9-]/g, '')
+const stateFile = path.join(stateDir, `wf-${phase}-${safeKey}.json`)
+let durationMs  = null
+
+if (event === 'workflow.started') {
+  fs.mkdirSync(stateDir, { recursive: true })
+  fs.writeFileSync(stateFile, JSON.stringify({ start_ms: nowMs }))
+}
+
+if (event === 'workflow.finished') {
+  if (fs.existsSync(stateFile)) {
+    const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'))
+    durationMs = nowMs - state.start_ms
+    fs.unlinkSync(stateFile)
+  }
+}
+
+const fixStateFile = path.join(stateDir, `fix-${phase}-${safeKey}.json`)
+
+if (event === 'fix.started') {
+  fs.mkdirSync(stateDir, { recursive: true })
+  fs.writeFileSync(fixStateFile, JSON.stringify({ start_ms: nowMs, fix_option: fixOption }))
+}
+
+if (event === 'fix.finished') {
+  if (fs.existsSync(fixStateFile)) {
+    const fixState = JSON.parse(fs.readFileSync(fixStateFile, 'utf8'))
+    durationMs = nowMs - fixState.start_ms
+    if (!fixOption) fixOption = fixState.fix_option
+    fs.unlinkSync(fixStateFile)
+  }
+}
+
+const attributes = [
+  { key: 'event',    value: { stringValue: event } },
+  { key: 'story_id', value: { stringValue: story } },
+  { key: 'epic_id',  value: { stringValue: epicId } },
+  { key: 'phase',    value: { stringValue: phase } },
+]
+
+if (from)              attributes.push({ key: 'from',        value: { stringValue: from } })
+if (to)                attributes.push({ key: 'to',          value: { stringValue: to } })
+if (fixOption)         attributes.push({ key: 'fix_option',  value: { stringValue: fixOption } })
+if (durationMs !== null) attributes.push({ key: 'duration_ms', value: { intValue: durationMs } })
+
+const otlpBody = {
+  resourceLogs: [
+    {
+      resource: {
+        attributes: [
+          { key: 'service.name', value: { stringValue: 'bmad' } },
+          { key: 'project_id',   value: { stringValue: projectId } },
+          { key: 'engineer',     value: { stringValue: engineer } },
+        ],
+      },
+      scopeLogs: [
+        {
+          scope: { name: 'bmad.observability' },
+          logRecords: [
+            {
+              timeUnixNano:         tsNano,
+              observedTimeUnixNano: tsNano,
+              severityNumber:       9,
+              severityText:         'INFO',
+              body:                 { stringValue: `${event} | story=${story} phase=${phase} project=${projectId} engineer=${engineer}` },
+              attributes,
+            },
+          ],
+        },
+      ],
+    },
+  ],
+}
+
+function parseHeaders(raw) {
+  const out = {}
+  if (!raw) return out
+  for (const pair of raw.split(',')) {
+    const idx = pair.indexOf('=')
+    if (idx === -1) continue
+    const key = pair.slice(0, idx).trim()
+    const val = pair.slice(idx + 1).trim()
+    if (key) out[key] = val
+  }
+  return out
+}
+
+;(async () => {
+  try {
+    const headers = {
+      'Content-Type': 'application/json',
+      ...parseHeaders(process.env.SA_OTLP_HEADERS),
+    }
+
+    const response = await fetch(`${otlpEndpoint}/v1/logs`, {
+      method:  'POST',
+      headers,
+      body:    JSON.stringify(otlpBody),
+    })
+    if (!response.ok) throw new Error(`HTTP ${response.status}`)
+
+    let msg = `[sa-emit] ${event} | story=${story} phase=${phase} project=${projectId} engineer=${engineer}`
+    if (durationMs !== null) msg += ` duration=${durationMs}ms`
+    console.log(msg)
+  } catch (_) {
+    const bufferDir = path.join(stateDir, 'buffer')
+    fs.mkdirSync(bufferDir, { recursive: true })
+    fs.appendFileSync(path.join(bufferDir, 'events.jsonl'), JSON.stringify(otlpBody) + '\n')
+    console.log(`[sa-emit] BUFFERED (collector unavailable) | ${event} story=${story}`)
+  }
+})()