@mestreyoda/fabrica 0.1.0

package/genesis/scripts/delivery-target-lib.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+genesis_normalize_delivery_target() {
+  local raw="${1:-}"
+  raw="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | sed -E 's/[[:space:]_]+/-/g')"
+  case "$raw" in
+    web|web-ui|webui|frontend|front-end|ui|interface|site|website|pwa)
+      printf '%s' "web-ui"
+      ;;
+    api|backend|service|rest|graphql|webhook)
+      printf '%s' "api"
+      ;;
+    cli|terminal|console|command-line|linha-de-comando)
+      printf '%s' "cli"
+      ;;
+    hybrid|fullstack|full-stack)
+      printf '%s' "hybrid"
+      ;;
+    *)
+      printf '%s' "unknown"
+      ;;
+  esac
+}
+
+genesis_detect_delivery_target_from_text() {
+  local text="${1:-}"
+  local lower
+  lower="$(printf '%s' "$text" | tr '[:upper:]' '[:lower:]')"
+
+  local has_web="false"
+  local has_api="false"
+  local has_cli="false"
+
+  if echo "$lower" | grep -Eqi '\b(app web|web app|site|website|frontend|front-end|interface|ui|ux|tela|página|pagina|dashboard|painel|pwa)\b'; then
+    has_web="true"
+  fi
+  if echo "$lower" | grep -Eqi '\b(api|endpoint|backend|rest|graphql|webhook|serviço|servico)\b'; then
+    has_api="true"
+  fi
+  if echo "$lower" | grep -Eqi '\b(cli|terminal|console|linha de comando|command line|comando|programinha|programa|script|calcular|converter|ferramenta)\b'; then
+    has_cli="true"
+  fi
+
+  local count=0
+  [[ "$has_web" == "true" ]] && count=$((count + 1))
+  [[ "$has_api" == "true" ]] && count=$((count + 1))
+  [[ "$has_cli" == "true" ]] && count=$((count + 1))
+
+  if [[ "$count" -gt 1 ]]; then
+    printf '%s' "hybrid"
+    return 0
+  fi
+  if [[ "$has_web" == "true" ]]; then
+    printf '%s' "web-ui"
+    return 0
+  fi
+  if [[ "$has_api" == "true" ]]; then
+    printf '%s' "api"
+    return 0
+  fi
+  if [[ "$has_cli" == "true" ]]; then
+    printf '%s' "cli"
+    return 0
+  fi
+
+  printf '%s' "unknown"
+}
+
+genesis_cross_validate_delivery_target() {
+  local spec_target="${1:-}"
+  local raw_idea="${2:-}"
+  local text_target
+  text_target="$(genesis_detect_delivery_target_from_text "$raw_idea")"
+
+  if [[ "$text_target" != "unknown" && "$spec_target" != "unknown" && "$text_target" != "$spec_target" ]]; then
+    echo "WARNING: delivery_target conflict — spec='$spec_target' vs text='$text_target'. Preferring text." >&2
+    printf '%s' "$text_target"
+    return 0
+  fi
+
+  if [[ "$spec_target" == "unknown" && "$text_target" != "unknown" ]]; then
+    printf '%s' "$text_target"
+    return 0
+  fi
+
+  printf '%s' "$spec_target"
+}

package/genesis/scripts/generate-qa-contract.sh

@@ -0,0 +1,188 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Step 7: Generate QA contract (qa.sh) from spec
+# Input: stdin JSON (with spec.acceptance_criteria)
+# Output: JSON with qa_contract to stdout
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/stack-detection-lib.sh"
+source "$SCRIPT_DIR/genesis-telemetry.sh"
+
+if [[ -n "${1:-}" && -f "${1:-}" ]]; then
+  INPUT="$(cat "$1")"
+else
+  INPUT="$(cat)"
+fi
+SESSION_ID="$(echo "$INPUT" | jq -r '.session_id')"
+SPEC="$(echo "$INPUT" | jq '.spec // {}')"
+TYPE="$(echo "$INPUT" | jq -r '.classification.type // "feature"')"
+METADATA="$(echo "$INPUT" | jq '.metadata // {}')"
+CLASSIFICATION="$(echo "$INPUT" | jq '.classification // {}')"
+INTERVIEW="$(echo "$INPUT" | jq '.interview // {}')"
+IMPACT="$(echo "$INPUT" | jq '.impact // {}')"
+PROJECT_MAP="$(echo "$INPUT" | jq '.project_map // {}')"
+SCAFFOLD="$(echo "$INPUT" | jq '.scaffold // {}')"
+STACK_HINT="$(echo "$SCAFFOLD" | jq -r '.stack // ""' | tr '[:upper:]' '[:lower:]')"
+
+genesis_metric_start "generate-qa-contract" "$SESSION_ID"
+echo "Generating QA contract for session $SESSION_ID..." >&2
+
+# Detect stack flags using shared stack-detection-lib.sh
+LANGUAGES="$(echo "$PROJECT_MAP" | jq -r '.stats.languages // [] | .[]' 2>/dev/null || echo "")"
+SCOPE_TEXT="$(echo "$SPEC" | jq -r '(.scope_v1 // []) | join(" ")' | tr '[:upper:]' '[:lower:]')"
+
+read -r IS_PY IS_JS IS_GO <<< "$(genesis_detect_stack_flags_from_context "$STACK_HINT" "$LANGUAGES" "$SCOPE_TEXT")"
+
+if ! $IS_PY && ! $IS_JS && ! $IS_GO; then
+  echo "No stack detected — qa.sh will fail closed until stack is explicit" >&2
+fi
+
+echo "Stack detected: PY=$IS_PY JS=$IS_JS GO=$IS_GO" >&2
+
+# Build acceptance criteria comments for qa.sh
+AC_COMMENTS=""
+AC_INDEX=0
+while IFS= read -r ac; do
+  [[ -z "$ac" ]] && continue
+  AC_INDEX=$((AC_INDEX + 1))
+  AC_COMMENTS="$AC_COMMENTS
+# AC$AC_INDEX: $ac"
+done < <(echo "$SPEC" | jq -r '.acceptance_criteria // [] | .[]')
+
+# Generate qa.sh script content
+QA_SCRIPT='#!/usr/bin/env bash
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+QA_VENV="${QA_VENV:-$HOME/.openclaw/qa-venv}"
+[ -d "$QA_VENV/bin" ] && export PATH="$QA_VENV/bin:$PATH"
+PASS=0; FAIL=0
+gate() { local n="$1"; shift; printf "==> %s\n" "$n"; if "$@"; then PASS=$((PASS+1)); printf "    PASS\n"; else FAIL=$((FAIL+1)); printf "    FAIL\n"; return 1; fi; }
+
+# SECURITY: This script output may be embedded in PR descriptions.
+# It must NEVER print environment variables, tokens, API keys, or host paths.
+
+# === Acceptance Criteria ==='"$AC_COMMENTS"'
+
+# === Stack Detection ==='
+
+QA_SCRIPT="$QA_SCRIPT"'
+if ! '"$IS_PY"' && ! '"$IS_JS"' && ! '"$IS_GO"'; then
+  echo "UNKNOWN STACK: unable to infer stack from scaffold/project map/spec."
+  echo "Update scaffold.stack or project_map.stats.languages and regenerate QA contract."
+  exit 1
+fi'
+
+if $IS_PY; then
+  QA_SCRIPT="$QA_SCRIPT"'
+IS_PY=true
+$IS_PY && command -v ruff >/dev/null && gate "Lint (Python)" ruff check . || true
+$IS_PY && command -v mypy >/dev/null && gate "Types (Python)" mypy . --ignore-missing-imports || true'
+fi
+
+if $IS_JS; then
+  QA_SCRIPT="$QA_SCRIPT"'
+IS_JS=true
+$IS_JS && [ -f node_modules/.bin/eslint ] && gate "Lint (JS/TS)" npx eslint . || true
+$IS_JS && [ -f tsconfig.json ] && gate "Types (TS)" npx tsc --noEmit || true'
+fi
+
+if $IS_GO; then
+  QA_SCRIPT="$QA_SCRIPT"'
+IS_GO=true
+$IS_GO && gate "Lint (Go)" go vet ./... || true'
+fi
+
+QA_SCRIPT="$QA_SCRIPT"'
+
+# === Security Gate ===
+command -v openclaw >/dev/null && gate "Security (ClawScan)" openclaw invoke --skill clawscan --tool scan-local --args-json '"'"'{"path":"."}'"'"' || true
+
+# === Test Gate ==='
+
+if $IS_PY; then
+  QA_SCRIPT="$QA_SCRIPT"'
+$IS_PY && gate "Tests (Python)" python -m pytest -v --tb=short || true'
+fi
+
+if $IS_JS; then
+  QA_SCRIPT="$QA_SCRIPT"'
+$IS_JS && gate "Tests (JS)" npm test || true'
+fi
+
+if $IS_GO; then
+  QA_SCRIPT="$QA_SCRIPT"'
+$IS_GO && gate "Tests (Go)" go test -v ./... || true'
+fi
+
+QA_SCRIPT="$QA_SCRIPT"'
+
+# === Coverage Gate (>= 80%) ===
+'
+
+if $IS_PY; then
+  QA_SCRIPT="$QA_SCRIPT"'
+$IS_PY && gate "Coverage (Python >=80%)" python -m pytest -q --cov=. --cov-report=term-missing --cov-fail-under=80 || true'
+fi
+
+if $IS_JS; then
+  QA_SCRIPT="$QA_SCRIPT"'
+$IS_JS && gate "Coverage (JS/TS >=80%)" npx vitest run --coverage --coverage.thresholds.lines=80 || true'
+fi
+
+if $IS_GO; then
+  QA_SCRIPT="$QA_SCRIPT"'
+$IS_GO && gate "Coverage (Go >=80%)" bash -lc '\''go test -coverprofile=coverage.out ./... && go tool cover -func=coverage.out | awk "/^total:/ {gsub(/%/,\"\",\\$3); exit !(\\$3>=80)}"'\'' || true'
+fi
+
+QA_SCRIPT="$QA_SCRIPT"'
+
+TOTAL=$((PASS+FAIL))
+if [[ "$TOTAL" -eq 0 ]]; then
+  echo "NO QA GATES EXECUTED"
+  exit 1
+fi
+echo "QA: $PASS/$TOTAL passed"
+[ "$FAIL" -gt 0 ] && echo "FAILED" && exit 1
+echo "ALL QA GATES PASSED"'
+
+# Build gates list
+GATES='["lint", "types", "security", "tests", "coverage"]'
+
+# Build acceptance tests from ACs
+ACCEPTANCE_TESTS="$(echo "$SPEC" | jq '[.acceptance_criteria // [] | .[] | {criterion: ., gate: "tests", automated: false}]')"
+
+echo "QA contract generated: $AC_INDEX acceptance criteria, gates=$(echo "$GATES" | jq 'length')" >&2
+
+jq -n \
+  --arg sid "$SESSION_ID" \
+  --arg script "$QA_SCRIPT" \
+  --argjson gates "$GATES" \
+  --argjson tests "$ACCEPTANCE_TESTS" \
+  --argjson spec "$SPEC" \
+  --argjson cls "$CLASSIFICATION" \
+  --argjson interview "$INTERVIEW" \
+  --argjson impact "$IMPACT" \
+  --argjson map "$PROJECT_MAP" \
+  --argjson scaffold "$SCAFFOLD" \
+  --argjson meta "$METADATA" \
+  '{
+    session_id: $sid,
+    step: "qa",
+    qa_contract: {
+      script_content: $script,
+      gates: $gates,
+      coverage_threshold: 80,
+      acceptance_tests: $tests
+    },
+    spec: $spec,
+    classification: $cls,
+    interview: $interview,
+    impact: $impact,
+    project_map: $map,
+    scaffold: $scaffold,
+    metadata: $meta
+  }'
+
+genesis_metric_end "ok"

package/genesis/scripts/generate-spec.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Step 4: Generate structured specification from classification + interview answers
+# Input: stdin JSON (classification + interview with answers)
+# Output: JSON with full spec to stdout
+# Note: The LLM fills answers via llm-task. This script structures them into
+#       the mandatory headings required by issue_checklist.py:
+#       Objetivo, Escopo V1, Fora de escopo, Acceptance Criteria, DoD, Restrições
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/delivery-target-lib.sh"
+
+if [[ -n "${1:-}" && -f "${1:-}" ]]; then
+  INPUT="$(cat "$1")"
+else
+  INPUT="$(cat)"
+fi
+SESSION_ID="$(echo "$INPUT" | jq -r '.session_id')"
+RAW_IDEA="$(echo "$INPUT" | jq -r '.raw_idea')"
+TYPE="$(echo "$INPUT" | jq -r '.classification.type')"
+CLASSIFICATION="$(echo "$INPUT" | jq '.classification')"
+INTERVIEW="$(echo "$INPUT" | jq '.interview // {}')"
+METADATA="$(echo "$INPUT" | jq '.metadata // {}')"
+
+echo "Generating specification for session $SESSION_ID (type=$TYPE)..." >&2
+
+# Extract structured data from the LLM interview output
+# The llm-task step should return a JSON with these fields
+TITLE="$(echo "$INPUT" | jq -r '.spec_data.title // .interview.spec_data.title // .raw_idea' | cut -c1-120)"
+OBJECTIVE="$(echo "$INPUT" | jq -r '.spec_data.objective // .interview.spec_data.objective // "See raw idea"')"
+SCOPE="$(echo "$INPUT" | jq '.spec_data.scope_v1 // .interview.spec_data.scope_v1 // [.raw_idea]')"
+OUT_OF_SCOPE="$(echo "$INPUT" | jq '.spec_data.out_of_scope // .interview.spec_data.out_of_scope // ["To be defined during implementation"]')"
+ACS="$(echo "$INPUT" | jq '.spec_data.acceptance_criteria // .interview.spec_data.acceptance_criteria // ["Feature works as described in the objective"]')"
+DOD="$(echo "$INPUT" | jq '.spec_data.definition_of_done // .interview.spec_data.definition_of_done // ["Code reviewed and merged", "Tests pass", "QA contract passes"]')"
+CONSTRAINTS="$(echo "$INPUT" | jq -r '.spec_data.constraints // .interview.spec_data.constraints // "None specified"')"
+RISKS="$(echo "$INPUT" | jq '.spec_data.risks // .interview.spec_data.risks // []')"
+DELIVERY_TARGET_RAW="$(echo "$INPUT" | jq -r '.spec_data.delivery_target // .interview.spec_data.delivery_target // .classification.delivery_target // .metadata.delivery_target // empty')"
+if [[ -z "$DELIVERY_TARGET_RAW" || "$DELIVERY_TARGET_RAW" == "null" ]]; then
+  DELIVERY_TARGET="$(genesis_detect_delivery_target_from_text "$RAW_IDEA")"
+else
+  DELIVERY_TARGET_NORMALIZED="$(genesis_normalize_delivery_target "$DELIVERY_TARGET_RAW")"
+  DELIVERY_TARGET="$(genesis_cross_validate_delivery_target "$DELIVERY_TARGET_NORMALIZED" "$RAW_IDEA")"
+fi
+
+# Validate minimum requirements
+scope_count="$(echo "$SCOPE" | jq 'length')"
+ac_count="$(echo "$ACS" | jq 'length')"
+dod_count="$(echo "$DOD" | jq 'length')"
+
+if [[ "$scope_count" -lt 1 ]]; then
+  echo "WARNING: Empty scope — using raw idea as scope item" >&2
+  SCOPE="$(jq -n --arg i "$RAW_IDEA" '[$i]')"
+fi
+
+if [[ "$ac_count" -lt 1 ]]; then
+  echo "WARNING: No acceptance criteria — adding default" >&2
+  ACS='["Feature works as described in the objective"]'
+fi
+
+if [[ "$dod_count" -lt 1 ]]; then
+  echo "WARNING: No definition of done — adding defaults" >&2
+  DOD='["Code reviewed and merged", "Tests pass", "QA contract passes"]'
+fi
+
+ACS_JOINED_LOWER="$(echo "$ACS" | jq -r 'join(" ")' | tr '[:upper:]' '[:lower:]')"
+append_ac() {
+  local item="$1"
+  ACS="$(echo "$ACS" | jq --arg i "$item" '. + [$i]')"
+}
+append_dod() {
+  local item="$1"
+  DOD="$(echo "$DOD" | jq --arg i "$item" '. + [$i]')"
+}
+
+case "$DELIVERY_TARGET" in
+  web-ui)
+    if ! echo "$ACS_JOINED_LOWER" | grep -Eqi '\b(tela|página|pagina|ui|interface|dashboard|fluxo)\b'; then
+      append_ac "Existe ao menos uma tela funcional do fluxo principal, navegavel de ponta a ponta."
+    fi
+    ;;
+  api)
+    if ! echo "$ACS_JOINED_LOWER" | grep -Eqi '\b(api|endpoint|rota|route|http|rest)\b'; then
+      append_ac "Existe ao menos um endpoint/API funcional do fluxo principal, com resposta valida."
+    fi
+    ;;
+  cli)
+    if ! echo "$ACS_JOINED_LOWER" | grep -Eqi '\b(cli|terminal|comando|linha de comando|console)\b'; then
+      append_ac "Existe ao menos um comando CLI funcional do fluxo principal."
+    fi
+    ;;
+  hybrid)
+    if ! echo "$ACS_JOINED_LOWER" | grep -Eqi '\b(tela|página|pagina|ui|interface|dashboard|fluxo)\b'; then
+      append_ac "Existe ao menos uma interface/tela funcional para o fluxo principal."
+    fi
+    if ! echo "$ACS_JOINED_LOWER" | grep -Eqi '\b(api|endpoint|rota|route|http|rest)\b'; then
+      append_ac "Existe ao menos uma API/endpoint funcional para suportar o fluxo principal."
+    fi
+    ;;
+esac
+
+# Auth requirements gate (hybrid policy):
+# - If idea indicates auth/per-profile needs and spec has no auth evidence,
+#   auto-append minimal AC/DoD to prevent contract drift.
+AUTH_REGEX='\b(login|autentic|senha|perfil|permiss|acesso|rbac|admin)\b'
+AUTH_SIGNAL=false
+AUTH_EVIDENCE=false
+AUTH_SIGNAL_TEXT="$(printf '%s %s' "$RAW_IDEA" "$OBJECTIVE" | tr '[:upper:]' '[:lower:]')"
+AUTH_EVIDENCE_TEXT="$(printf '%s %s %s' "$OBJECTIVE" "$(echo "$SCOPE" | jq -r 'join(" ")')" "$(echo "$ACS" | jq -r 'join(" ")')" | tr '[:upper:]' '[:lower:]')"
+
+if echo "$AUTH_SIGNAL_TEXT" | grep -Eqi "$AUTH_REGEX"; then
+  AUTH_SIGNAL=true
+fi
+if echo "$AUTH_EVIDENCE_TEXT" | grep -Eqi "$AUTH_REGEX"; then
+  AUTH_EVIDENCE=true
+fi
+if [[ "$AUTH_SIGNAL" == "true" && "$AUTH_EVIDENCE" != "true" ]]; then
+  append_ac "Usuarios autenticados conseguem iniciar sessao com credenciais validas."
+  append_ac "Acoes criticas exigem autorizacao por perfil (ex.: admin/operador/leitura)."
+  append_dod "Existe teste cobrindo autorizacao por perfil em ao menos um fluxo critico."
+  AUTH_EVIDENCE=true
+fi
+
+CONSTRAINTS_BASE="$CONSTRAINTS"
+if [[ -n "$CONSTRAINTS_BASE" && "$CONSTRAINTS_BASE" != "None specified" ]]; then
+  CONSTRAINTS="$CONSTRAINTS_BASE Delivery target: $DELIVERY_TARGET."
+else
+  CONSTRAINTS="Delivery target: $DELIVERY_TARGET."
+fi
+ac_count="$(echo "$ACS" | jq 'length')"
+dod_count="$(echo "$DOD" | jq 'length')"
+META_ENRICHED="$(echo "$METADATA" | jq --argjson signal "$AUTH_SIGNAL" --argjson evidence "$AUTH_EVIDENCE" '. + {auth_gate: {signal: $signal, evidence: $evidence}}')"
+
+echo "Spec: title='$TITLE', scope=$scope_count items, ACs=$ac_count, DoD=$dod_count" >&2
+
+jq -n \
+  --arg sid "$SESSION_ID" \
+  --arg raw_idea "$RAW_IDEA" \
+  --arg title "$TITLE" \
+  --arg type "$TYPE" \
+  --arg objective "$OBJECTIVE" \
+  --argjson scope "$SCOPE" \
+  --argjson oos "$OUT_OF_SCOPE" \
+  --argjson acs "$ACS" \
+  --argjson dod "$DOD" \
+  --arg constraints "$CONSTRAINTS" \
+  --argjson risks "$RISKS" \
+  --arg delivery_target "$DELIVERY_TARGET" \
+  --argjson cls "$CLASSIFICATION" \
+  --argjson interview "$INTERVIEW" \
+  --argjson meta "$META_ENRICHED" \
+  '{
+    session_id: $sid,
+    step: "spec",
+    raw_idea: $raw_idea,
+    spec: {
+      title: $title,
+      type: $type,
+      objective: $objective,
+      scope_v1: $scope,
+      out_of_scope: $oos,
+      acceptance_criteria: $acs,
+      definition_of_done: $dod,
+      constraints: $constraints,
+      risks: $risks,
+      delivery_target: $delivery_target
+    },
+    classification: $cls,
+    interview: $interview,
+    metadata: $meta
+  }'

package/genesis/scripts/genesis-telemetry.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# genesis-telemetry.sh — Structured telemetry for Genesis pipeline steps
+# Emits JSON metrics to a log file for observability.
+# shellcheck shell=bash
+
+if [ -z "${BASH_VERSION:-}" ]; then
+  echo "ERROR: genesis-telemetry.sh requires bash." >&2
+  return 1 2>/dev/null || exit 1
+fi
+
+[[ -n "${_GENESIS_TELEMETRY_LOADED:-}" ]] && return 0
+_GENESIS_TELEMETRY_LOADED=1
+
+GENESIS_METRICS_FILE="${GENESIS_METRICS_FILE:-$HOME/.openclaw/workspace/logs/genesis-metrics.jsonl}"
+mkdir -p "$(dirname "$GENESIS_METRICS_FILE")" 2>/dev/null || true
+
+# _genesis_epoch_ms — current time in milliseconds
+_genesis_epoch_ms() {
+  if date +%s%3N >/dev/null 2>&1; then
+    date +%s%3N
+  else
+    echo "$(date +%s)000"
+  fi
+}
+
+# genesis_metric_start <step_name> <session_id>
+# Call at the beginning of a pipeline step. Stores start time in env.
+# Returns: nothing (sets _GENESIS_METRIC_START_MS)
+genesis_metric_start() {
+  local step="${1:-unknown}"
+  local session_id="${2:-}"
+  export _GENESIS_METRIC_STEP="$step"
+  export _GENESIS_METRIC_SESSION="$session_id"
+  export _GENESIS_METRIC_START_MS="$(_genesis_epoch_ms)"
+}
+
+# genesis_metric_end <status> [error_message]
+# Call at the end of a pipeline step. Emits JSON metric line.
+# status: "ok", "error", "skipped"
+genesis_metric_end() {
+  local status="${1:-ok}"
+  local error_msg="${2:-}"
+  local end_ms duration_ms
+
+  end_ms="$(_genesis_epoch_ms)"
+  if [[ -n "${_GENESIS_METRIC_START_MS:-}" ]]; then
+    duration_ms=$(( end_ms - _GENESIS_METRIC_START_MS ))
+  else
+    duration_ms=0
+  fi
+
+  jq -n -c \
+    --arg step "${_GENESIS_METRIC_STEP:-unknown}" \
+    --arg session_id "${_GENESIS_METRIC_SESSION:-}" \
+    --arg status "$status" \
+    --argjson duration_ms "$duration_ms" \
+    --arg error "$error_msg" \
+    --arg timestamp "$(date -Iseconds)" \
+    '{
+      step: $step,
+      session_id: $session_id,
+      status: $status,
+      duration_ms: $duration_ms,
+      timestamp: $timestamp
+    }
+    + (if $error != "" then {error: $error} else {} end)
+    ' >> "$GENESIS_METRICS_FILE" 2>/dev/null || true
+
+  unset _GENESIS_METRIC_STEP _GENESIS_METRIC_SESSION _GENESIS_METRIC_START_MS
+}
+
+# genesis_emit_metric <step> <session_id> <status> <duration_ms> [error]
+# Direct metric emission (for scripts that don't use start/end pattern).
+genesis_emit_metric() {
+  local step="${1:-unknown}"
+  local session_id="${2:-}"
+  local status="${3:-ok}"
+  local duration_ms="${4:-0}"
+  local error_msg="${5:-}"
+
+  jq -n -c \
+    --arg step "$step" \
+    --arg session_id "$session_id" \
+    --arg status "$status" \
+    --argjson duration_ms "$duration_ms" \
+    --arg error "$error_msg" \
+    --arg timestamp "$(date -Iseconds)" \
+    '{
+      step: $step,
+      session_id: $session_id,
+      status: $status,
+      duration_ms: $duration_ms,
+      timestamp: $timestamp
+    }
+    + (if $error != "" then {error: $error} else {} end)
+    ' >> "$GENESIS_METRICS_FILE" 2>/dev/null || true
+}