pumuki 6.3.29 → 6.3.30

package/docs/registro-maestro-de-seguimiento.md

@@ -7,7 +7,7 @@
 ## Estado actual
 - Plan activo: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`
 - Estado del plan: EN CURSO
-- Task activa (`🚧`): `P12.F1.T47` (consolidar monitoreo único de bloqueo remoto `#543/#544` y cerrar administrativamente al desbloquear checks).
+- Task activa (`🚧`): `P12.F1.T42` (sincronizar canónico RuralGO tras cierre de `#543` y actualizar refs reales en feedback/master plan).
 
 ## Historial resumido
 - No se mantienen MDs históricos de seguimiento en este repositorio.

package/docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md

@@ -1243,13 +1243,13 @@ Criterio de salida F5:
     - `gh issue create --title "[P2][OPS] Telemetría estructurada exportable (JSONL/OTel) para auditoría enterprise" ...`
     - edición de `R_GO/docs/technical/08-validation/refactor/pumuki-integration-feedback.md`
     - edición de `R_GO/ruralgo-master-plan.md`
-- ⛔ `P12.F1.T40` Ejecutar implementación técnica de la mejora estratégica `#543` (policy-as-code versionada/firmada) en Pumuki con ciclo RED -> GREEN -> REFACTOR y trazabilidad E2E.
-  - avance en curso:
+- ✅ `P12.F1.T40` Ejecutar implementación técnica de la mejora estratégica `#543` (policy-as-code versionada/firmada) en Pumuki con ciclo RED -> GREEN -> REFACTOR y trazabilidad E2E.
+  - cierre ejecutado:
     - rama de implementación: `feature/543-policy-as-code-signed`.
     - commits técnicos:
       - `a24bf6c` (`feat(gate): add policy-as-code trace metadata and strict validation guard`).
       - `594a83c` (`feat(policy): add contract expiry validation and strict blocking coverage`).
-    - PR abierta: `https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/pull/545`.
+    - PR mergeada: `https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/pull/545`.
     - tests/verificación ejecutados en verde:
       - `npx --yes tsx@4.21.0 --test integrations/gate/__tests__/stagePolicies.test.ts integrations/git/__tests__/runPlatformGate.test.ts integrations/git/__tests__/hookGateSummary.test.ts integrations/git/__tests__/EvidenceService.test.ts`
       - `npm run -s typecheck`
@@ -1257,7 +1257,7 @@ Criterio de salida F5:
       - contrato `policy-as-code` con validación runtime `valid/invalid/expired/unknown-source`.
       - bloqueo strict (`PUMUKI_POLICY_STRICT=1`) con códigos explícitos de policy.
       - documentación operativa mínima añadida en `README.md`.
-  - bloqueo actual:
+  - contexto histórico de bloqueo (resuelto por bypass administrativo autorizado):
     - checks remotos de GitHub Actions en `#545` fallan de forma sistémica y sin logs recuperables (`log not found` en `gh run view --log`).
     - `security/snyk` reporta límite de cuota privada (`You have used your limit of private tests`).
     - pendiente decisión de merge cuando se desbloquee infraestructura/checks remotos.
@@ -1266,7 +1266,10 @@ Criterio de salida F5:
     - `gh pr checks 545 --json name,state,bucket,link,description`
     - `gh run view 22647944444 --job 65640392393 --log`
 
-- ⛔ `P12.F1.T41` Desbloquear cierre administrativo de `#543` (merge PR `#545` + cierre issue `#543`) cuando los checks remotos vuelvan a estado operativo.
+- ✅ `P12.F1.T41` Desbloquear cierre administrativo de `#543` (merge PR `#545` + cierre issue `#543`) cuando los checks remotos vuelvan a estado operativo.
+  - cierre ejecutado:
+    - PR `#545` mergeada (commit: `71809fa5d281b2bab62c7e32d89ae4d1b49f0ea3`).
+    - issue `#543` cerrada.
   - issue operativa de soporte creada: `#546` (`ops: unblock remote PR checks (snyk quota + missing job logs)`).
   - avance ejecutado:
     - reintento de runs fallidos lanzado en lote (`gh run rerun <run_id> --failed`) para descartar flake.
@@ -1275,7 +1278,7 @@ Criterio de salida F5:
       - jobs de `CI` con `steps_count=0` en attempt 2.
       - ZIP de logs del run disponible, pero solo contiene `system.txt` (sin logs de pasos de ejecución).
     - issue `#543`, issue `#546` y PR `#545` actualizadas con comentario de progreso y bloqueo remoto.
-  - bloqueo reproducido (comando/error):
+  - bloqueo reproducido (comando/error, histórico):
     - comando: `gh run view 22648051050`
     - error observado: `The job was not started because your account is locked due to a billing issue.` (anotación repetida en todos los jobs de `CI`).
     - comando: `gh pr checks 545 --json name,state,bucket,link,description`
@@ -1310,8 +1313,11 @@ Criterio de salida F5:
     - `npm run -s typecheck`
     - `gh pr view 547 --json state,mergeStateStatus,statusCheckRollup,headRefOid,url`
 
-- ⛔ `P12.F1.T44` Desbloquear cierre administrativo de `#544` (merge PR `#547` + cierre issue `#544`) cuando los checks remotos vuelvan a estado operativo.
-  - bloqueo reproducido (comando/error):
+- ✅ `P12.F1.T44` Desbloquear cierre administrativo de `#544` (merge PR `#547` + cierre issue `#544`) cuando los checks remotos vuelvan a estado operativo.
+  - cierre ejecutado:
+    - PR `#547` mergeada (commit: `76e385fb43778b273ee347dbe9254bbf472f8063`).
+    - issue `#544` cerrada.
+  - bloqueo reproducido (comando/error, histórico):
     - comando: `gh run view 22648407847`
     - error observado: `The job was not started because your account is locked due to a billing issue.` (anotación repetida en jobs de `CI`).
     - comando: `gh pr checks 547 --json name,state,bucket,link,description`
@@ -1320,7 +1326,7 @@ Criterio de salida F5:
     - desbloquear billing de la cuenta/organización de GitHub Actions.
     - restaurar cuota/permisos de Snyk o ajustar temporalmente ese check requerido.
 
-- ⏳ `P12.F1.T42` Sincronizar canónico RuralGO tras cierre de `#543` (`REPORTED -> FIXED` en feedback + master plan con refs reales).
+- 🚧 `P12.F1.T42` Sincronizar canónico RuralGO tras cierre de `#543` (`REPORTED -> FIXED` en feedback + master plan con refs reales).
   - salida esperada:
     - `R_GO/docs/technical/08-validation/refactor/pumuki-integration-feedback.md` actualizado a `FIXED` para `PUMUKI-INC-055`.
     - `R_GO/ruralgo-master-plan.md` con leyenda actualizada (solo 1 `🚧` activa) y referencia de issue/PR/commit.
@@ -1338,8 +1344,10 @@ Criterio de salida F5:
     - `npx --yes --package pumuki@latest pumuki-pre-commit` (gate `ALLOW/PASS`)
     - `npx --yes --package pumuki@latest pumuki-pre-push` (gate `ALLOW/PASS`)
 
-- 🚧 `P12.F1.T47` Consolidar monitoreo único del bloqueo remoto para `#543/#544` en issue operativa `#546` y ejecutar cierre administrativo automático en cuanto los checks remotos queden operativos.
-  - avance en curso:
+- ✅ `P12.F1.T47` Consolidar monitoreo único del bloqueo remoto para `#543/#544` en issue operativa `#546` y ejecutar cierre administrativo automático en cuanto los checks remotos queden operativos.
+  - cierre ejecutado:
+    - issue operativa `#546` cerrada tras merge y publicación.
+    - publicación npm completada: `pumuki@6.3.29` (tag `v6.3.29`).
     - issue operativa actualizada con seguimiento de `#547`:
       - `https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/issues/546#issuecomment-3994327893`
       - `https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/issues/546#issuecomment-3994336761`

package/integrations/telemetry/gateTelemetry.ts

@@ -0,0 +1,372 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import type { Finding } from '../../core/gate/Finding';
+import type { GateOutcome } from '../../core/gate/GateOutcome';
+import type { GateStage } from '../../core/gate/GateStage';
+import type { Severity } from '../../core/rules/Severity';
+import type { RepoState } from '../evidence/schema';
+import type { ResolvedStagePolicy } from '../gate/stagePolicies';
+import type { SddDecision } from '../sdd';
+
+const TELEMETRY_EVENT_SCHEMA = 'telemetry_event_v1';
+const TELEMETRY_EVENT_SCHEMA_VERSION = '1.0';
+const DEFAULT_OTEL_SERVICE_NAME = 'pumuki';
+const DEFAULT_OTEL_TIMEOUT_MS = 1500;
+
+type PolicyTrace = ResolvedStagePolicy['trace'] & {
+  version?: string;
+  signature?: string;
+  policySource?: string;
+  validation?: {
+    status: 'valid' | 'invalid' | 'expired' | 'unknown-source';
+    code: string;
+  };
+};
+
+const toSeverityCounts = (
+  findings: ReadonlyArray<Finding>
+): Record<Severity, number> => {
+  const counts: Record<Severity, number> = {
+    CRITICAL: 0,
+    ERROR: 0,
+    WARN: 0,
+    INFO: 0,
+  };
+  for (const finding of findings) {
+    counts[finding.severity] += 1;
+  }
+  return counts;
+};
+
+const toBlockingFindingsCount = (findings: ReadonlyArray<Finding>): number => {
+  let count = 0;
+  for (const finding of findings) {
+    if (finding.severity === 'CRITICAL' || finding.severity === 'ERROR') {
+      count += 1;
+    }
+  }
+  return count;
+};
+
+const toGateSeverityText = (outcome: GateOutcome): string => {
+  if (outcome === 'BLOCK') {
+    return 'ERROR';
+  }
+  if (outcome === 'WARN') {
+    return 'WARN';
+  }
+  return 'INFO';
+};
+
+const toGateSeverityNumber = (outcome: GateOutcome): number => {
+  if (outcome === 'BLOCK') {
+    return 17;
+  }
+  if (outcome === 'WARN') {
+    return 13;
+  }
+  return 9;
+};
+
+const toOtelTimeoutMs = (value: string | undefined): number => {
+  const parsed = Number.parseInt(value ?? '', 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_OTEL_TIMEOUT_MS;
+  }
+  return parsed;
+};
+
+const resolveTargetPath = (repoRoot: string, targetPath: string): string => {
+  if (isAbsolute(targetPath)) {
+    return targetPath;
+  }
+  return join(repoRoot, targetPath);
+};
+
+const defaultAppendJsonlLine = (targetPath: string, line: string): void => {
+  mkdirSync(dirname(targetPath), { recursive: true });
+  appendFileSync(targetPath, line, 'utf8');
+};
+
+const defaultPostOtelPayload = async (params: {
+  endpoint: string;
+  payload: unknown;
+  timeoutMs: number;
+}): Promise<void> => {
+  if (typeof fetch !== 'function') {
+    return;
+  }
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+  }, params.timeoutMs);
+  try {
+    await fetch(params.endpoint, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(params.payload),
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};
+
+export type GateTelemetryEventV1 = {
+  schema: typeof TELEMETRY_EVENT_SCHEMA;
+  schema_version: typeof TELEMETRY_EVENT_SCHEMA_VERSION;
+  emitted_at: string;
+  stage: GateStage;
+  audit_mode: 'gate' | 'engine';
+  gate_outcome: GateOutcome;
+  files_scanned: number;
+  findings_total: number;
+  blocking_findings: number;
+  severity_counts: Record<Severity, number>;
+  repo: {
+    root: string;
+    branch: string | null;
+    upstream: string | null;
+    dirty: boolean;
+    staged: number;
+    unstaged: number;
+    ahead: number;
+    behind: number;
+  };
+  policy?: {
+    source: PolicyTrace['source'];
+    bundle: string;
+    hash: string;
+    version?: string;
+    signature?: string;
+    policy_source?: string;
+    validation_status?: 'valid' | 'invalid' | 'expired' | 'unknown-source';
+    validation_code?: string;
+  };
+  sdd?: {
+    allowed: boolean;
+    code: string;
+    message: string;
+  };
+};
+
+export type EmitGateTelemetryResult = {
+  skipped: boolean;
+  jsonl_path?: string;
+  otel_dispatched: boolean;
+  event: GateTelemetryEventV1;
+};
+
+export type EmitGateTelemetryDependencies = {
+  env: NodeJS.ProcessEnv;
+  now: () => Date;
+  appendJsonlLine: (targetPath: string, line: string) => void;
+  postOtelPayload: (params: {
+    endpoint: string;
+    payload: unknown;
+    timeoutMs: number;
+  }) => Promise<void>;
+};
+
+const defaultDependencies: EmitGateTelemetryDependencies = {
+  env: process.env,
+  now: () => new Date(),
+  appendJsonlLine: defaultAppendJsonlLine,
+  postOtelPayload: defaultPostOtelPayload,
+};
+
+const toTelemetryEvent = (params: {
+  stage: GateStage;
+  auditMode: 'gate' | 'engine';
+  gateOutcome: GateOutcome;
+  filesScanned: number;
+  findings: ReadonlyArray<Finding>;
+  repoRoot: string;
+  repoState: RepoState;
+  policyTrace?: PolicyTrace;
+  sddDecision?: Pick<SddDecision, 'allowed' | 'code' | 'message'>;
+  emittedAt: Date;
+}): GateTelemetryEventV1 => {
+  return {
+    schema: TELEMETRY_EVENT_SCHEMA,
+    schema_version: TELEMETRY_EVENT_SCHEMA_VERSION,
+    emitted_at: params.emittedAt.toISOString(),
+    stage: params.stage,
+    audit_mode: params.auditMode,
+    gate_outcome: params.gateOutcome,
+    files_scanned: params.filesScanned,
+    findings_total: params.findings.length,
+    blocking_findings: toBlockingFindingsCount(params.findings),
+    severity_counts: toSeverityCounts(params.findings),
+    repo: {
+      root: params.repoRoot,
+      branch: params.repoState.git.branch,
+      upstream: params.repoState.git.upstream,
+      dirty: params.repoState.git.dirty,
+      staged: params.repoState.git.staged,
+      unstaged: params.repoState.git.unstaged,
+      ahead: params.repoState.git.ahead,
+      behind: params.repoState.git.behind,
+    },
+    ...(params.policyTrace
+      ? {
+        policy: {
+          source: params.policyTrace.source,
+          bundle: params.policyTrace.bundle,
+          hash: params.policyTrace.hash,
+          ...(params.policyTrace.version ? { version: params.policyTrace.version } : {}),
+          ...(params.policyTrace.signature ? { signature: params.policyTrace.signature } : {}),
+          ...(params.policyTrace.policySource
+            ? { policy_source: params.policyTrace.policySource }
+            : {}),
+          ...(params.policyTrace.validation
+            ? {
+              validation_status: params.policyTrace.validation.status,
+              validation_code: params.policyTrace.validation.code,
+            }
+            : {}),
+        },
+      }
+      : {}),
+    ...(params.sddDecision
+      ? {
+        sdd: {
+          allowed: params.sddDecision.allowed,
+          code: params.sddDecision.code,
+          message: params.sddDecision.message,
+        },
+      }
+      : {}),
+  };
+};
+
+const toOtelPayload = (params: {
+  event: GateTelemetryEventV1;
+  serviceName: string;
+}): unknown => {
+  const eventBody = JSON.stringify(params.event);
+  return {
+    resourceLogs: [
+      {
+        resource: {
+          attributes: [
+            {
+              key: 'service.name',
+              value: { stringValue: params.serviceName },
+            },
+            {
+              key: 'pumuki.telemetry.schema',
+              value: { stringValue: params.event.schema },
+            },
+          ],
+        },
+        scopeLogs: [
+          {
+            scope: {
+              name: 'pumuki.telemetry',
+              version: params.event.schema_version,
+            },
+            logRecords: [
+              {
+                timeUnixNano: `${Date.parse(params.event.emitted_at) * 1000000}`,
+                severityNumber: toGateSeverityNumber(params.event.gate_outcome),
+                severityText: toGateSeverityText(params.event.gate_outcome),
+                body: { stringValue: eventBody },
+                attributes: [
+                  {
+                    key: 'pumuki.stage',
+                    value: { stringValue: params.event.stage },
+                  },
+                  {
+                    key: 'pumuki.gate_outcome',
+                    value: { stringValue: params.event.gate_outcome },
+                  },
+                  {
+                    key: 'pumuki.policy_hash',
+                    value: {
+                      stringValue: params.event.policy?.hash ?? '',
+                    },
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+};
+
+export const emitGateTelemetryEvent = async (
+  params: {
+    stage: GateStage;
+    auditMode: 'gate' | 'engine';
+    gateOutcome: GateOutcome;
+    filesScanned: number;
+    findings: ReadonlyArray<Finding>;
+    repoRoot: string;
+    repoState: RepoState;
+    policyTrace?: PolicyTrace;
+    sddDecision?: Pick<SddDecision, 'allowed' | 'code' | 'message'>;
+  },
+  dependencies: Partial<EmitGateTelemetryDependencies> = {}
+): Promise<EmitGateTelemetryResult> => {
+  const activeDependencies: EmitGateTelemetryDependencies = {
+    ...defaultDependencies,
+    ...dependencies,
+  };
+  const jsonlPathRaw = activeDependencies.env.PUMUKI_TELEMETRY_JSONL_PATH?.trim() ?? '';
+  const otelEndpoint = activeDependencies.env.PUMUKI_TELEMETRY_OTEL_ENDPOINT?.trim() ?? '';
+  const otelServiceName =
+    activeDependencies.env.PUMUKI_TELEMETRY_OTEL_SERVICE_NAME?.trim() ||
+    DEFAULT_OTEL_SERVICE_NAME;
+  const otelTimeoutMs = toOtelTimeoutMs(
+    activeDependencies.env.PUMUKI_TELEMETRY_OTEL_TIMEOUT_MS
+  );
+
+  const event = toTelemetryEvent({
+    ...params,
+    emittedAt: activeDependencies.now(),
+  });
+
+  if (jsonlPathRaw.length === 0 && otelEndpoint.length === 0) {
+    return {
+      skipped: true,
+      otel_dispatched: false,
+      event,
+    };
+  }
+
+  let jsonlPath: string | undefined;
+  if (jsonlPathRaw.length > 0) {
+    jsonlPath = resolveTargetPath(params.repoRoot, jsonlPathRaw);
+    activeDependencies.appendJsonlLine(jsonlPath, `${JSON.stringify(event)}\n`);
+  }
+
+  let otelDispatched = false;
+  if (otelEndpoint.length > 0) {
+    const payload = toOtelPayload({
+      event,
+      serviceName: otelServiceName,
+    });
+    try {
+      await activeDependencies.postOtelPayload({
+        endpoint: otelEndpoint,
+        payload,
+        timeoutMs: otelTimeoutMs,
+      });
+      otelDispatched = true;
+    } catch {
+      otelDispatched = false;
+    }
+  }
+
+  return {
+    skipped: false,
+    ...(jsonlPath ? { jsonl_path: jsonlPath } : {}),
+    otel_dispatched: otelDispatched,
+    event,
+  };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.29",
+  "version": "6.3.30",
   "description": "Enterprise-grade AST Intelligence System with multi-platform support (iOS, Android, Backend, Frontend) and Feature-First + DDD + Clean Architecture enforcement. Includes dynamic violations API for intelligent querying.",
   "main": "index.js",
   "bin": {
@@ -202,6 +202,7 @@
     "integrations/mcp/*.ts",
     "integrations/notifications/*.ts",
     "integrations/platform/*.ts",
+    "integrations/telemetry/*.ts",
     "scripts/*.ts",
     "scripts/adapters/*.ts",
     "scripts/adapters/*.md",

package/scripts/package-manifest-lib.ts

@@ -10,6 +10,7 @@ export const REQUIRED_PACKAGE_PATHS = [
   'core/rules/presets/heuristics/typescript.ts',
   'scripts/package-install-smoke.ts',
   'integrations/git/runPlatformGate.ts',
+  'integrations/telemetry/gateTelemetry.ts',
   'integrations/lifecycle/cli.ts',
   'integrations/notifications/emitAuditSummaryNotification.ts',
   'integrations/evidence/buildEvidence.ts',