pumuki 6.3.29 → 6.3.31

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.F2.T51` (publicar release con el hardening `#551` y cerrar trazabilidad final en canónico + master).
 
 ## 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,10 +1326,21 @@ 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).
-  - 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.
+- ✅ `P12.F1.T42` Sincronizar canónico RuralGO tras cierre de `#543` (`REPORTED -> FIXED` en feedback + master plan con refs reales).
+  - cierre ejecutado:
+    - se resolvió el bloqueo histórico de rama creando una rama docs limpia desde `origin/develop` en `R_GO`: `docs/rgo-sync-issue-543-fixed-20260304`.
+    - commit documental atómico aplicado: `66d88dacb` (`docs(validation): sync canonical issue 543 to fixed`).
+    - PR abierta en `R_GO`: `https://github.com/SwiftEnProfundidad/R_GO/pull/1503`.
+    - canónico actualizado en la PR:
+      - `docs/technical/08-validation/refactor/pumuki-integration-feedback.md` (`PUMUKI-INC-055 => ✅ FIXED`).
+      - `ruralgo-master-plan.md` (`#543 => ✅`, leyenda recalculada).
+  - evidencia:
+    - `git -C /tmp/rgo-sync-issue-543-*/ commit -m "docs(validation): sync canonical issue 543 to fixed"`
+    - `git -C /tmp/rgo-sync-issue-543-*/ push -u origin docs/rgo-sync-issue-543-fixed-20260304`
+    - `gh pr create --base develop --head docs/rgo-sync-issue-543-fixed-20260304`
+    - hook gates en verde:
+      - `pre-commit => ALLOW/PASS`
+      - `pre-push => ALLOW/PASS`
 
 - ✅ `P12.F1.T46` Sincronizar canónico RuralGO en estado intermedio de `#544` (`REPORTED` con refs reales de issue/branch/PR/commit/evidencia) y alinear master plan con una única mejora `🚧`.
   - cierre ejecutado:
@@ -1338,8 +1355,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`
@@ -1670,10 +1689,58 @@ Criterio de salida F5:
       - `gh run rerun 22648216106 --failed` (rerun solicitado en iteración actual).
       - `gh run rerun 22670371464 --failed` (rerun solicitado en iteración actual).
 
-- ⏳ `P12.F1.T45` Sincronizar canónico RuralGO tras cierre de `#544` (`REPORTED -> FIXED` en feedback + master plan con refs reales).
+- ✅ `P12.F1.T48` Corregir regresión crítica de packaging en `pumuki@6.3.29` (módulo telemetry ausente en npm) y publicar patch release.
+  - cierre ejecutado:
+    - issue creada: `#548` (`bug: npm package misses integrations/telemetry and breaks hooks at runtime`).
+    - fix implementado:
+      - `package.json` incluye `integrations/telemetry/*.ts` en `files`.
+      - `scripts/package-manifest-lib.ts` exige `integrations/telemetry/gateTelemetry.ts` como ruta requerida.
+    - PR mergeada: `#549` (commit de merge `1075752d338f38354772781b5e32e0face35189c`).
+    - issue `#548` cerrada.
+    - release publicada: `pumuki@6.3.30` + tag `v6.3.30`.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test scripts/__tests__/package-manifest-lib.test.ts scripts/__tests__/check-package-manifest.test.ts`
+    - `npm run -s validation:package-manifest`
+    - `npm pack --json --dry-run | rg "integrations/telemetry/gateTelemetry.ts"`
+    - `npm run -s typecheck`
+    - `npm publish --access public`
+
+- ✅ `P12.F1.T45` Sincronizar canónico RuralGO tras cierre de `#544` (`REPORTED -> FIXED` en feedback + master plan con refs reales).
+  - cierre ejecutado:
+    - rama docs creada y publicada: `docs/rgo-sync-issue-544-fixed-20260304`.
+    - PR abierta y mergeada: `R_GO#1504` (`https://github.com/SwiftEnProfundidad/R_GO/pull/1504`).
+    - commit de merge en `develop`: `5c0306ba14ab59511a10d12d01a35911481154e3`.
+  - evidencia:
+    - `R_GO/docs/technical/08-validation/refactor/pumuki-integration-feedback.md` actualizado a `✅ FIXED` para `PUMUKI-INC-056`.
+    - `R_GO/ruralgo-master-plan.md` actualizado con leyenda y siguiente mejora estratégica activa.
+    - hooks en verde durante commit/push de la rama docs (`PRE_COMMIT=ALLOW`, `PRE_PUSH=ALLOW`).
+
+- ✅ `P12.F2.T49` Ejecutar la siguiente mejora estratégica pendiente: suite contractual multi-repo de regresión enterprise (issue -> rama -> PR -> evidencia).
+  - cierre ejecutado:
+    - issue creada y priorizada: `#551` (`feature: suite contractual multi-repo de regresión enterprise`).
+    - sincronización canónica RuralGO aplicada y mergeada: `R_GO#1505` (`https://github.com/SwiftEnProfundidad/R_GO/pull/1505`).
+    - commit de merge en `R_GO/develop`: `64e40d2365f3edf1137cf70a038a638398503db1`.
+  - evidencia:
+    - `R_GO/docs/technical/08-validation/refactor/pumuki-integration-feedback.md` actualizado con `PUMUKI-INC-057` en estado `🚧 REPORTED (#551)`.
+    - `R_GO/ruralgo-master-plan.md` actualizado con mejora estratégica activa referenciada a `#551`.
+
+- ✅ `P12.F2.T50` Ejecutar implementación técnica de la suite contractual multi-repo (`#551`) con ciclo RED -> GREEN -> REFACTOR y trazabilidad E2E.
+  - cierre ejecutado:
+    - rama técnica creada: `feature/551-enterprise-contract-suite`.
+    - PR abierta y mergeada: `#553` (`https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/pull/553`).
+    - issue cerrada: `#551`.
+    - commit de merge en `develop`: `0a3a005f004f6a65bb33946450cdb382af1a59f6`.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test scripts/__tests__/enterprise-contract-suite-args-lib.test.ts scripts/__tests__/enterprise-contract-suite-report-lib.test.ts`
+    - `npm run -s typecheck`
+    - `npm run -s validation:contract-suite:enterprise -- --json`
+    - `npm run -s validation:package-manifest`
+
+- 🚧 `P12.F2.T51` Publicar release que incluya el hardening `#551` (suite contractual) y dejar trazabilidad final en canónico + master.
   - salida esperada:
-    - `R_GO/docs/technical/08-validation/refactor/pumuki-integration-feedback.md` actualizado a `FIXED` para `PUMUKI-INC-056`.
-    - `R_GO/ruralgo-master-plan.md` con leyenda final actualizada y referencia de merge real.
+    - versión npm publicada con el MVP de suite contractual multi-repo.
+    - canónico RuralGO y master plan alineados con refs de release.
+    - estado operativo preparado para siguiente bloque de mejoras.
 
 Criterio de salida F6:
 - veredicto final trazable y cierre administrativo completo.

package/docs/validation/README.md

@@ -15,6 +15,7 @@ Este directorio contiene solo documentación oficial y estable de validación pa
 
 - Master de seguimiento: `docs/registro-maestro-de-seguimiento.md`.
 - Plan activo: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`.
+- Suite contractual enterprise (MVP): `npm run -s validation:contract-suite:enterprise`.
 
 ## Política de higiene
 

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.31",
   "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": {
@@ -108,6 +108,7 @@
     "validation:package-smoke": "node --import tsx scripts/package-install-smoke.ts --mode=block",
     "validation:package-smoke:minimal": "node --import tsx scripts/package-install-smoke.ts --mode=minimal",
     "validation:lifecycle-smoke": "node --import tsx scripts/package-install-smoke.ts --mode=minimal",
+    "validation:contract-suite:enterprise": "node --import tsx scripts/run-enterprise-contract-suite.ts",
     "validation:c020-benchmark": "node --import tsx scripts/run-c020-benchmark.ts",
     "validation:clean-artifacts": "npx --yes tsx@4.21.0 scripts/clean-validation-artifacts.ts",
     "skills:compile": "npx --yes tsx@4.21.0 scripts/compile-skills-lock.ts",
@@ -202,6 +203,7 @@
     "integrations/mcp/*.ts",
     "integrations/notifications/*.ts",
     "integrations/platform/*.ts",
+    "integrations/telemetry/*.ts",
     "scripts/*.ts",
     "scripts/adapters/*.ts",
     "scripts/adapters/*.md",

package/scripts/enterprise-contract-suite-args-lib.ts

@@ -0,0 +1,60 @@
+import { resolve } from 'node:path';
+import type { EnterpriseContractSuiteOptions } from './enterprise-contract-suite-contract';
+
+export const DEFAULT_ENTERPRISE_CONTRACT_REPORT_PATH =
+  '.audit-reports/enterprise-contract-suite/report.json';
+
+export const DEFAULT_ENTERPRISE_CONTRACT_SUMMARY_PATH =
+  '.audit-reports/enterprise-contract-suite/summary.md';
+
+export const parseEnterpriseContractSuiteArgs = (
+  argv: ReadonlyArray<string>,
+  cwd = process.cwd()
+): EnterpriseContractSuiteOptions => {
+  const options: EnterpriseContractSuiteOptions = {
+    repoRoot: resolve(cwd),
+    reportPath: DEFAULT_ENTERPRISE_CONTRACT_REPORT_PATH,
+    summaryPath: DEFAULT_ENTERPRISE_CONTRACT_SUMMARY_PATH,
+    printJson: false,
+  };
+
+  for (const arg of argv) {
+    if (arg === '--json') {
+      options.printJson = true;
+      continue;
+    }
+
+    if (arg.startsWith('--repo=')) {
+      const value = arg.slice('--repo='.length).trim();
+      if (!value) {
+        throw new Error('Flag --repo requires a non-empty path.');
+      }
+      options.repoRoot = resolve(value);
+      continue;
+    }
+
+    if (arg.startsWith('--out=')) {
+      const value = arg.slice('--out='.length).trim();
+      if (!value) {
+        throw new Error('Flag --out requires a non-empty path.');
+      }
+      options.reportPath = value;
+      continue;
+    }
+
+    if (arg.startsWith('--summary=')) {
+      const value = arg.slice('--summary='.length).trim();
+      if (!value) {
+        throw new Error('Flag --summary requires a non-empty path.');
+      }
+      options.summaryPath = value;
+      continue;
+    }
+
+    throw new Error(
+      `Unsupported argument "${arg}". Allowed: --repo=<path> --out=<path> --summary=<path> --json`
+    );
+  }
+
+  return options;
+};

package/scripts/enterprise-contract-suite-contract.ts

@@ -0,0 +1,31 @@
+export type EnterpriseContractProfileId = 'minimal' | 'block';
+
+export type EnterpriseContractProfileSpec = {
+  id: EnterpriseContractProfileId;
+  mode: 'minimal' | 'block';
+  expectedExitCode: number;
+};
+
+export type EnterpriseContractProfileResult = {
+  id: EnterpriseContractProfileId;
+  mode: 'minimal' | 'block';
+  command: string;
+  expectedExitCode: number;
+  exitCode: number;
+  status: 'PASS' | 'FAIL';
+};
+
+export type EnterpriseContractSuiteReport = {
+  suiteVersion: '1';
+  generatedAt: string;
+  repoRoot: string;
+  profiles: ReadonlyArray<EnterpriseContractProfileResult>;
+  overall: 'PASS' | 'FAIL';
+};
+
+export type EnterpriseContractSuiteOptions = {
+  repoRoot: string;
+  reportPath: string;
+  summaryPath: string;
+  printJson: boolean;
+};

package/scripts/enterprise-contract-suite-report-lib.ts

@@ -0,0 +1,45 @@
+import type {
+  EnterpriseContractProfileResult,
+  EnterpriseContractSuiteReport,
+} from './enterprise-contract-suite-contract';
+
+export const resolveEnterpriseContractOverall = (
+  profiles: ReadonlyArray<EnterpriseContractProfileResult>
+): 'PASS' | 'FAIL' =>
+  profiles.every((profile) => profile.status === 'PASS') ? 'PASS' : 'FAIL';
+
+export const buildEnterpriseContractReport = (params: {
+  repoRoot: string;
+  generatedAt?: string;
+  profiles: ReadonlyArray<EnterpriseContractProfileResult>;
+}): EnterpriseContractSuiteReport => ({
+  suiteVersion: '1',
+  generatedAt: params.generatedAt ?? new Date().toISOString(),
+  repoRoot: params.repoRoot,
+  profiles: params.profiles,
+  overall: resolveEnterpriseContractOverall(params.profiles),
+});
+
+export const renderEnterpriseContractSummary = (
+  report: EnterpriseContractSuiteReport
+): string => {
+  const lines: string[] = [
+    '# Enterprise Contract Suite Summary',
+    '',
+    `- Overall: ${report.overall}`,
+    `- Generated At: ${report.generatedAt}`,
+    `- Repo Root: ${report.repoRoot}`,
+    '',
+    '## Profiles',
+    '',
+  ];
+
+  for (const profile of report.profiles) {
+    lines.push(
+      `- ${profile.id}: status=${profile.status} expected_exit=${profile.expectedExitCode} actual_exit=${profile.exitCode}`
+    );
+  }
+
+  lines.push('');
+  return lines.join('\n');
+};

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',

package/scripts/run-enterprise-contract-suite.ts

@@ -0,0 +1,78 @@
+import { dirname, join } from 'node:path';
+import { writeFileSync } from 'node:fs';
+import {
+  parseEnterpriseContractSuiteArgs,
+} from './enterprise-contract-suite-args-lib';
+import {
+  buildEnterpriseContractReport,
+  renderEnterpriseContractSummary,
+} from './enterprise-contract-suite-report-lib';
+import type {
+  EnterpriseContractProfileResult,
+  EnterpriseContractProfileSpec,
+} from './enterprise-contract-suite-contract';
+import { ensureDirectory } from './package-install-smoke-file-lib';
+import { runCommand } from './package-install-smoke-command-lib';
+
+const PROFILE_SPECS: ReadonlyArray<EnterpriseContractProfileSpec> = [
+  {
+    id: 'minimal',
+    mode: 'minimal',
+    // The minimal fixture intentionally omits platform skill contracts to assert strict governance blocking.
+    expectedExitCode: 1,
+  },
+  {
+    id: 'block',
+    mode: 'block',
+    // The block fixture is expected to complete successfully as a deterministic BLOCK smoke scenario.
+    expectedExitCode: 0,
+  },
+];
+
+const runProfile = (
+  repoRoot: string,
+  profile: EnterpriseContractProfileSpec
+): EnterpriseContractProfileResult => {
+  const args = ['--import', 'tsx', 'scripts/package-install-smoke.ts', `--mode=${profile.mode}`];
+  const result = runCommand({
+    cwd: repoRoot,
+    executable: 'node',
+    args,
+  });
+
+  return {
+    id: profile.id,
+    mode: profile.mode,
+    command: `node ${args.join(' ')}`,
+    expectedExitCode: profile.expectedExitCode,
+    exitCode: result.exitCode,
+    status: result.exitCode === profile.expectedExitCode ? 'PASS' : 'FAIL',
+  };
+};
+
+const writeTextFile = (repoRoot: string, relativePath: string, content: string): void => {
+  const filePath = join(repoRoot, relativePath);
+  ensureDirectory(dirname(filePath));
+  writeFileSync(filePath, content, 'utf8');
+};
+
+const main = (): number => {
+  const options = parseEnterpriseContractSuiteArgs(process.argv.slice(2));
+  const results = PROFILE_SPECS.map((profile) => runProfile(options.repoRoot, profile));
+
+  const report = buildEnterpriseContractReport({
+    repoRoot: options.repoRoot,
+    profiles: results,
+  });
+
+  writeTextFile(options.repoRoot, options.reportPath, `${JSON.stringify(report, null, 2)}\n`);
+  writeTextFile(options.repoRoot, options.summaryPath, renderEnterpriseContractSummary(report));
+
+  if (options.printJson) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  }
+
+  return report.overall === 'PASS' ? 0 : 1;
+};
+
+process.exit(main());