pumuki 6.3.37 → 6.3.38

package/VERSION

@@ -1 +1 @@
-v6.3.37
+v6.3.38

package/docs/README.md

@@ -5,7 +5,7 @@ Canonical index for active Pumuki documentation.
 ## Seguimiento Activo (único)
 
 - Maestro: `docs/registro-maestro-de-seguimiento.md`
-- Plan activo: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`
+- Plan activo: `docs/seguimiento-activo-pumuki-saas-supermercados.md`
 - Política: una sola tarea en construcción (`🚧`) en el plan activo.
 
 ## Product and Architecture

package/docs/RELEASE_NOTES.md

@@ -5,6 +5,33 @@ Detailed commit history remains available through Git history (`git log` / `git
 
 ## 2026-03 (enterprise hardening updates)
 
+### 2026-03-04 (v6.3.38)
+
+- Blocked notification UX hardening for macOS:
+  - short, human-readable Spanish banner (`🔴 Pumuki bloqueado`) with stage + summarized cause.
+  - remediation-first body (`Solución: ...`) to maximize visibility in truncated notification banners.
+- Optional blocked-dialog workflow (`PUMUKI_MACOS_BLOCKED_DIALOG=1`):
+  - full cause/remediation modal for critical blocks.
+  - anti-spam controls in dialog:
+    - `Mantener activas`
+    - `Silenciar 30 min`
+    - `Desactivar`
+  - `giving up after 15` timeout to avoid local execution hangs.
+- Notification delivery contract update:
+  - config supports `muteUntil` in `.pumuki/system-notifications.json`.
+  - delivery result now reports `reason=muted` while silence window is active.
+- Regression baseline alignment:
+  - `integrations/git/__tests__/stageRunners.test.ts` updated to run with core skills enabled in test harness, matching current gate contract and eliminating false failures.
+- Traceability:
+  - commits: `2f957a2`, `ceb1849`, `98fc108`, `ae90f31`
+- Consumer quick verification:
+  - `npx --yes tsx@4.21.0 --test scripts/__tests__/framework-menu-system-notifications.test.ts`
+  - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/stageRunners.test.ts`
+  - `PUMUKI_MACOS_BLOCKED_DIALOG=1 npx --yes tsx@4.21.0 -e "import { emitSystemNotification } from './scripts/framework-menu-system-notifications-lib'; console.log(JSON.stringify(emitSystemNotification({ repoRoot: process.cwd(), event: { kind: 'gate.blocked', stage: 'PRE_COMMIT', totalViolations: 1, causeCode: 'BACKEND_AVOID_EXPLICIT_ANY', causeMessage: 'Avoid explicit any in backend code.', remediation: 'Tipa el valor y elimina any explícito en backend.' } })));"`
+  - expected signal:
+    - banner appears with concise remediation text,
+    - optional dialog appears with anti-spam actions when flag is enabled.
+
 ### 2026-03-04 (v6.3.37)
 
 - Policy-as-code enterprise hardening shipped:

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

@@ -5,14 +5,15 @@
 - Referenciar un único plan activo con fases, tasks y leyenda.
 
 ## Estado actual
-- Plan activo: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`
-- Estado del plan: EN CURSO
-- Última task cerrada (`✅`): `P12.F2.T72` (hardening `policy-as-code` completado: issue `#606` cerrada con PR `#608`).
-- Task activa (`🚧`): `P12.F2.T73` (preparar/publicar release incremental con el hardening de `#606`).
+- Plan activo: `docs/seguimiento-activo-pumuki-saas-supermercados.md`
+- Estado del plan: EJECUCION
+- Última task cerrada (`✅`): Fase 3.2 (actualización de `CHANGELOG.md` + `docs/RELEASE_NOTES.md` con fixes reales).
+- Task activa (`🚧`): Fase 3.3 publicación de versión.
+- Nuevos pendientes añadidos (`⏳`): sin cambios.
 
 ## Historial resumido
-- No se mantienen MDs históricos de seguimiento en este repositorio.
-- La trazabilidad histórica relevante debe consolidarse dentro del plan activo o en documentación oficial no temporal.
+- Bloque RuralGO cerrado: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`.
+- Se inicia bloque SAAS_SUPERMERCADOS con plan activo único y legible.
 
 ## Regla de operación
 - Debe existir exactamente una task `🚧` en el plan activo.

package/docs/seguimiento-activo-pumuki-saas-supermercados.md

@@ -0,0 +1,77 @@
+# Plan Activo Pumuki SAAS Supermercados
+
+## Leyenda
+
+- ✅ Cerrado
+- 🚧 En construccion (maximo 1)
+- ⏳ Pendiente
+- ⛔ Bloqueado
+
+## Objetivo
+
+- Resolver e implementar bugs y mejoras reportados en:
+  - `/Users/juancarlosmerlosalbarracin/Developer/Projects/SAAS:APP_SUPERMERCADOS/docs/pumuki/PUMUKI_BUGS_MEJORAS.md`
+- Mantener trazabilidad: hallazgo -> fix -> test -> release notes.
+
+## Fase 0. Intake y priorizacion
+
+- ✅ Consolidar hallazgos y deduplicar causas raiz del MD canónico.
+- ✅ Priorizar por impacto inicial:
+  - P1: `PUMUKI-001`, `PUMUKI-003`, `PUMUKI-005`, `PUMUKI-007`
+  - P2: `PUMUKI-002`, `PUMUKI-004`, `PUMUKI-006`
+
+## Fase 1. Bugs P1 (ejecucion tecnica)
+
+- ✅ PUMUKI-001: Compatibilidad de receipt MCP entre stages (`PRE_WRITE` vs `PRE_COMMIT`) sin bloqueo falso.
+- ✅ PUMUKI-003: Endurecer resolución de binarios en hooks/scripts para evitar `command not found`.
+- ✅ PUMUKI-005: Soporte robusto para repos con `:` en path (evitar dependencia frágil de PATH).
+- ✅ PUMUKI-007: Soportar repos sin commits (`HEAD` ausente) sin error ambiguo.
+
+## Fase 2. Mejoras P2
+
+- ✅ PUMUKI-002: Rule-pack opcional de atomicidad Git + trazabilidad de commit message.
+- ✅ PUMUKI-004: Mejorar diagnóstico de hooks efectivos en escenarios versionados/custom.
+- ✅ PUMUKI-006: Alinear `package_version` reportada por MCP con versión local efectiva del repo consumidor.
+
+## Fase 2.1 Paridad legacy (CLI vs MCP) en SAAS_SUPERMERCADOS
+
+- ✅ PUMUKI-008: Feedback iterativo en chat no equivalente a flujo legacy.
+  - Evidencia: en ejecución MCP no aparece feedback operativo por iteración del modelo como en el grafo legacy.
+  - Esperado: resumen corto y humano en cada iteración (`stage`, `decision`, `next_action`).
+  - Entregable: tool MCP de pre-flight para chat con salida estable y accionable.
+- ✅ PUMUKI-009: Desalineación operativa entre `ai_gate_check` y `pre_flight_check`.
+  - Evidencia: `ai_gate_check => BLOCKED (EVIDENCE_STALE)` mientras `pre_flight_check => allowed=true`.
+  - Esperado: criterio homogéneo o explicación explícita y trazable de por qué uno bloquea y el otro permite.
+  - Entregable: decisión unificada desde el mismo evaluador/política.
+- ✅ PUMUKI-010: Respuesta no accionable en `auto_execute_ai_start` para confianza media.
+  - Evidencia: `success=true`, `action=ask`, `message=Medium confidence (undefined%)...`.
+  - Esperado: `next_action` determinista + confidence numérico consistente + remediación concreta.
+  - Entregable: contrato MCP estable (`confidence_pct`, `reason_code`, `next_action`).
+- ✅ PUMUKI-011: Notificación macOS obligatoria en cualquier bloqueo de gate/fase.
+  - Requisito hard: cuando Pumuki bloquee (`PRE_WRITE`, `PRE_COMMIT`, `PRE_PUSH`, `CI`), lanzar notificación nativa macOS con sonido.
+  - Contenido mínimo: `🔴 BLOQUEADO`, causa exacta (`code + message`) y `cómo solucionarlo` (`next_action`).
+  - Entregable: comportamiento consistente en CLI, hooks y herramientas MCP con formato humano.
+  - Ajuste UX (2026-03-04): mensaje corto y legible para humanos.
+  - Nuevo formato: subtítulo con causa resumida + cuerpo iniciando por `Solución: ...` para que no se corte la remediación.
+  - ✅ PoC (2026-03-04): modo opcional de diálogo completo para bloqueo en macOS con `PUMUKI_MACOS_BLOCKED_DIALOG=1` (banner corto + modal con causa/solución completas).
+  - ✅ PoC anti-spam (2026-03-04): diálogo con acciones de control (`Mantener activas`, `Silenciar 30 min`, `Desactivar`) + timeout automático de 15s para no bloquear flujo.
+
+## Decisión de producto (hard)
+
+- La automatización es obligatoria: minimizar pasos manuales en bootstrap, pre-flight, gate y remediación.
+- Objetivo operativo: que instalación + wiring de agente dejen el flujo listo para ejecutar y reportar bloqueos sin intervención manual extra.
+
+## Aclaración operativa (para no perderse)
+
+- CLI: lo ejecutan hooks Git (`pre-commit`, `pre-push`) y comandos manuales (`pumuki ...`).
+- MCP: lo consume el agente/herramienta (Codex/Cursor/Windsurf...) cuando está configurado.
+- `pumuki install`: instala hooks Git y bootstrap base.
+- `pumuki adapter install --agent=<...>`: cablea hooks de agente + servidores MCP en el entorno del agente.
+
+## Fase 3. Cierre
+
+- ✅ Ejecutar suite de tests de regresión afectada.
+  - Evidencia (2026-03-04): `npx --yes tsx@4.21.0 --test scripts/__tests__/framework-menu-system-notifications.test.ts integrations/git/__tests__/stageRunners.test.ts integrations/lifecycle/__tests__/lifecycle.test.ts` -> `44 pass / 0 fail`.
+- ✅ Actualizar `CHANGELOG.md` y `docs/RELEASE_NOTES.md` con fixes reales.
+  - Evidencia (2026-03-04): se documenta en `Unreleased` (CHANGELOG) y en `next patch candidate` (RELEASE_NOTES) el paquete de mejoras `PUMUKI-011` + baseline test alignment.
+- 🚧 Publicar versión cuando las tareas en construcción/pending críticas estén cerradas.

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

@@ -1994,10 +1994,34 @@ Criterio de salida F5:
     - `npx --yes tsx@4.21.0 --test integrations/gate/__tests__/stagePolicies.test.ts integrations/git/__tests__/runPlatformGate.test.ts integrations/lifecycle/__tests__/status.test.ts integrations/lifecycle/__tests__/doctor.test.ts integrations/lifecycle/__tests__/cli.test.ts` => `81 passed, 0 failed`.
     - `npm run -s typecheck` => `exit 0`.
 
-- 🚧 `P12.F2.T73` Preparar y publicar release con el hardening de `#606`.
+- ✅ `P12.F2.T73` Preparar y publicar release con el hardening de `#606`.
+  - cierre ejecutado:
+    - release branch creada: `release/6.3.37`.
+    - versionado aplicado en `package.json`, `package-lock.json`, `VERSION` y release notes.
+    - PR de release mergeada: `#610` (`commit acbdb73`).
+    - publicación npm completada con éxito (`npm publish --access public`).
+    - propagación validada: `latest=6.3.37`.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/gate/__tests__/stagePolicies.test.ts integrations/git/__tests__/runPlatformGate.test.ts integrations/lifecycle/__tests__/status.test.ts integrations/lifecycle/__tests__/doctor.test.ts integrations/lifecycle/__tests__/cli.test.ts` => `81 passed, 0 failed`.
+    - `npm run -s typecheck` => `exit 0`.
+    - `npm view pumuki dist-tags --json` => `"latest": "6.3.37"`.
+    - `npm view pumuki@6.3.37 version` => `6.3.37`.
+
+- ✅ **Cierre consolidado del bloque P12.F2** (ID interno: `P12.F2.T74`).
+  - cierre ejecutado:
+    - bloque `P12.F2` consolidado con trazabilidad completa (issues/PRs/releases y evidencias de validación).
+    - backlog siguiente preparado en modo standby, sin deuda técnica abierta obligatoria del bloque actual.
+    - confirmada publicación estable `pumuki@6.3.37` como baseline para nuevos proyectos.
+  - evidencia:
+    - `gh issue view 606 --json state` => `CLOSED`.
+    - `gh pr view 608 --json state,mergedAt` => `MERGED`.
+    - `gh pr view 610 --json state,mergedAt` => `MERGED`.
+    - `npm view pumuki dist-tags --json` => `"latest": "6.3.37"`.
+
+- 🚧 **En espera de nueva orden** (ID interno: `P12.F2.T75`; sin deuda técnica pendiente de este bloque).
   - salida esperada:
-    - versionar release incremental y notas de publicación.
-    - publicar en npm y verificar propagación `dist-tags`.
+    - mantener una sola `🚧` activa por política del tablero.
+    - no ejecutar trabajo técnico nuevo hasta instrucción explícita del usuario.
 
 Criterio de salida F6:
 - veredicto final trazable y cierre administrativo completo.

package/integrations/gate/evaluateAiGate.ts

@@ -81,6 +81,12 @@ const DEFAULT_MAX_AGE_SECONDS: Readonly<Record<AiGateStage, number>> = {
 };
 
 const DEFAULT_PROTECTED_BRANCHES = new Set(['main', 'master', 'develop', 'dev']);
+const MCP_RECEIPT_STAGE_ORDER: Readonly<Record<AiGateStage, number>> = {
+  PRE_WRITE: 0,
+  PRE_COMMIT: 1,
+  PRE_PUSH: 2,
+  CI: 3,
+};
 
 const toErrorViolation = (code: string, message: string): AiGateViolation => ({
   code,
@@ -335,6 +341,13 @@ const toPolicyStage = (stage: AiGateStage): SkillsStage => {
   return stage;
 };
 
+const isMcpReceiptStageCompatible = (params: {
+  receiptStage: AiGateStage;
+  requestedStage: AiGateStage;
+}): boolean => {
+  return MCP_RECEIPT_STAGE_ORDER[params.receiptStage] >= MCP_RECEIPT_STAGE_ORDER[params.requestedStage];
+};
+
 const collectMcpReceiptViolations = (params: {
   required: boolean;
   stage: AiGateStage;
@@ -405,11 +418,16 @@ const collectMcpReceiptViolations = (params: {
       )
     );
   }
-  if (receiptRead.receipt.stage !== params.stage) {
+  if (
+    !isMcpReceiptStageCompatible({
+      receiptStage: receiptRead.receipt.stage,
+      requestedStage: params.stage,
+    })
+  ) {
     violations.push(
       toErrorViolation(
         'MCP_ENTERPRISE_RECEIPT_STAGE_MISMATCH',
-        `MCP receipt stage mismatch (${receiptRead.receipt.stage} != ${params.stage}).`
+        `MCP receipt stage mismatch (${receiptRead.receipt.stage} incompatible with ${params.stage}).`
       )
     );
   }

package/integrations/git/GitService.ts

@@ -2,6 +2,7 @@ import { execFileSync as runBinarySync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { Fact } from '../../core/facts/Fact';
+import type { GitChange } from './gitDiffUtils';
 import { parseNameStatus, hasAllowedExtension, buildFactsFromChanges } from './gitDiffUtils';
 export { parseNameStatus } from './gitDiffUtils';
 
@@ -77,7 +78,16 @@ export class GitService implements IGitService {
   }
 
   getStagedAndUnstagedFacts(extensions: ReadonlyArray<string>): ReadonlyArray<Fact> {
-    const trackedChanges = parseNameStatus(this.runGit(['diff', '--name-status', 'HEAD']))
+    const hasHeadCommit = this.hasHeadCommit();
+    const trackedNameStatus = hasHeadCommit
+      ? this.runGit(['diff', '--name-status', 'HEAD'])
+      : [
+        this.runGit(['diff', '--cached', '--name-status']),
+        this.runGit(['diff', '--name-status']),
+      ]
+        .filter((chunk) => chunk.trim().length > 0)
+        .join('\n');
+    const trackedChanges = this.deduplicateChangesByPath(parseNameStatus(trackedNameStatus))
       .filter((change) => hasAllowedExtension(change.path, extensions));
     const untrackedPaths = this.runGit(['ls-files', '--others', '--exclude-standard'])
       .split('\n')
@@ -100,6 +110,23 @@ export class GitService implements IGitService {
     );
   }
 
+  private hasHeadCommit(): boolean {
+    try {
+      this.runGit(['rev-parse', '--verify', 'HEAD']);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private deduplicateChangesByPath(changes: ReadonlyArray<GitChange>): ReadonlyArray<GitChange> {
+    const byPath = new Map<string, GitChange>();
+    for (const change of changes) {
+      byPath.set(change.path, change);
+    }
+    return Array.from(byPath.values());
+  }
+
   private readWorkingTreeFile(repoRoot: string, filePath: string): string {
     try {
       return readFileSync(join(repoRoot, filePath), 'utf8');

package/integrations/git/gitAtomicity.ts

@@ -0,0 +1,274 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { GitService, type IGitService } from './GitService';
+
+export type GitAtomicityStage = 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
+
+export type GitAtomicityViolation = {
+  code:
+    | 'GIT_ATOMICITY_TOO_MANY_FILES'
+    | 'GIT_ATOMICITY_TOO_MANY_SCOPES'
+    | 'GIT_ATOMICITY_COMMIT_MESSAGE_TRACEABILITY';
+  message: string;
+  remediation: string;
+};
+
+export type GitAtomicityEvaluation = {
+  enabled: boolean;
+  allowed: boolean;
+  violations: ReadonlyArray<GitAtomicityViolation>;
+};
+
+type GitAtomicityConfig = {
+  enabled: boolean;
+  maxFiles: number;
+  maxScopes: number;
+  enforceCommitMessagePattern: boolean;
+  commitMessagePattern: string;
+};
+
+const ATOMICITY_CONFIG_FILE = '.pumuki/git-atomicity.json';
+const DEFAULT_COMMIT_PATTERN =
+  '^(feat|fix|chore|refactor|docs|test|perf|build|ci|revert)(\\([^)]+\\))?:\\s.+$';
+
+const defaultConfig: GitAtomicityConfig = {
+  enabled: false,
+  maxFiles: 25,
+  maxScopes: 2,
+  enforceCommitMessagePattern: true,
+  commitMessagePattern: DEFAULT_COMMIT_PATTERN,
+};
+
+const parseBooleanEnv = (value: string | undefined): boolean | undefined => {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized.length === 0) {
+    return undefined;
+  }
+  if (normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on') {
+    return true;
+  }
+  if (normalized === '0' || normalized === 'false' || normalized === 'no' || normalized === 'off') {
+    return false;
+  }
+  return undefined;
+};
+
+const parsePositiveIntegerEnv = (value: string | undefined): number | undefined => {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const parsed = Number.parseInt(value.trim(), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return undefined;
+  }
+  return parsed;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.trim().length > 0;
+
+const parseFileConfig = (repoRoot: string): Partial<GitAtomicityConfig> | undefined => {
+  const filePath = resolve(repoRoot, ATOMICITY_CONFIG_FILE);
+  if (!existsSync(filePath)) {
+    return undefined;
+  }
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(filePath, 'utf8'));
+    if (!isRecord(parsed)) {
+      return undefined;
+    }
+    const fromFile: Partial<GitAtomicityConfig> = {};
+    if (typeof parsed.enabled === 'boolean') {
+      fromFile.enabled = parsed.enabled;
+    }
+    if (Number.isInteger(parsed.maxFiles) && Number(parsed.maxFiles) > 0) {
+      fromFile.maxFiles = Number(parsed.maxFiles);
+    }
+    if (Number.isInteger(parsed.maxScopes) && Number(parsed.maxScopes) > 0) {
+      fromFile.maxScopes = Number(parsed.maxScopes);
+    }
+    if (typeof parsed.enforceCommitMessagePattern === 'boolean') {
+      fromFile.enforceCommitMessagePattern = parsed.enforceCommitMessagePattern;
+    }
+    if (isNonEmptyString(parsed.commitMessagePattern)) {
+      fromFile.commitMessagePattern = parsed.commitMessagePattern;
+    }
+    return fromFile;
+  } catch {
+    return undefined;
+  }
+};
+
+const resolveConfig = (repoRoot: string): GitAtomicityConfig => {
+  const fromFile = parseFileConfig(repoRoot) ?? {};
+
+  return {
+    enabled:
+      parseBooleanEnv(process.env.PUMUKI_GIT_ATOMICITY_ENABLED)
+      ?? fromFile.enabled
+      ?? defaultConfig.enabled,
+    maxFiles:
+      parsePositiveIntegerEnv(process.env.PUMUKI_GIT_ATOMICITY_MAX_FILES)
+      ?? fromFile.maxFiles
+      ?? defaultConfig.maxFiles,
+    maxScopes:
+      parsePositiveIntegerEnv(process.env.PUMUKI_GIT_ATOMICITY_MAX_SCOPES)
+      ?? fromFile.maxScopes
+      ?? defaultConfig.maxScopes,
+    enforceCommitMessagePattern:
+      parseBooleanEnv(process.env.PUMUKI_GIT_ATOMICITY_ENFORCE_COMMIT_PATTERN)
+      ?? fromFile.enforceCommitMessagePattern
+      ?? defaultConfig.enforceCommitMessagePattern,
+    commitMessagePattern:
+      process.env.PUMUKI_GIT_ATOMICITY_COMMIT_PATTERN?.trim()
+      || fromFile.commitMessagePattern
+      || defaultConfig.commitMessagePattern,
+  };
+};
+
+const parseLines = (value: string): ReadonlyArray<string> =>
+  value
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+const resolveScopeKey = (filePath: string): string => {
+  const normalized = filePath.replace(/\\/g, '/').trim();
+  const segments = normalized.split('/').filter((segment) => segment.length > 0);
+  if (segments.length === 0) {
+    return '';
+  }
+  if (
+    (segments[0] === 'apps' || segments[0] === 'packages' || segments[0] === 'services')
+    && segments.length >= 2
+  ) {
+    return `${segments[0]}/${segments[1]}`;
+  }
+  return segments[0] ?? '';
+};
+
+const collectChangedPaths = (params: {
+  git: IGitService;
+  repoRoot: string;
+  stage: GitAtomicityStage;
+  fromRef?: string;
+  toRef?: string;
+}): ReadonlyArray<string> => {
+  if (params.stage === 'PRE_COMMIT') {
+    return parseLines(
+      params.git.runGit(['diff', '--cached', '--name-only', '--diff-filter=ACMR'], params.repoRoot)
+    );
+  }
+  if (!params.fromRef || !params.toRef) {
+    return [];
+  }
+  return parseLines(
+    params.git.runGit(
+      ['diff', '--name-only', '--diff-filter=ACMR', `${params.fromRef}..${params.toRef}`],
+      params.repoRoot
+    )
+  );
+};
+
+const collectCommitSubjects = (params: {
+  git: IGitService;
+  repoRoot: string;
+  fromRef?: string;
+  toRef?: string;
+}): ReadonlyArray<string> => {
+  if (!params.fromRef || !params.toRef) {
+    return [];
+  }
+  return parseLines(
+    params.git.runGit(['log', '--format=%s', `${params.fromRef}..${params.toRef}`], params.repoRoot)
+  );
+};
+
+export const evaluateGitAtomicity = (params: {
+  git?: IGitService;
+  repoRoot?: string;
+  stage: GitAtomicityStage;
+  fromRef?: string;
+  toRef?: string;
+}): GitAtomicityEvaluation => {
+  const git = params.git ?? new GitService();
+  const repoRoot = params.repoRoot ? resolve(params.repoRoot) : git.resolveRepoRoot();
+  const config = resolveConfig(repoRoot);
+  if (!config.enabled) {
+    return {
+      enabled: false,
+      allowed: true,
+      violations: [],
+    };
+  }
+
+  const violations: GitAtomicityViolation[] = [];
+  const changedPaths = collectChangedPaths({
+    git,
+    repoRoot,
+    stage: params.stage,
+    fromRef: params.fromRef,
+    toRef: params.toRef,
+  });
+
+  if (changedPaths.length > config.maxFiles) {
+    violations.push({
+      code: 'GIT_ATOMICITY_TOO_MANY_FILES',
+      message:
+        `Git atomicity guard blocked at ${params.stage}: changed_files=${changedPaths.length} exceeds max_files=${config.maxFiles}.`,
+      remediation: `Divide los cambios en commits más pequeños (máximo ${config.maxFiles} archivos por commit).`,
+    });
+  }
+
+  const scopeKeys = new Set(
+    changedPaths
+      .map((filePath) => resolveScopeKey(filePath))
+      .filter((scopeKey) => scopeKey.length > 0)
+  );
+  if (scopeKeys.size > config.maxScopes) {
+    violations.push({
+      code: 'GIT_ATOMICITY_TOO_MANY_SCOPES',
+      message:
+        `Git atomicity guard blocked at ${params.stage}: changed_scopes=${scopeKeys.size} exceeds max_scopes=${config.maxScopes}.`,
+      remediation: `Agrupa cambios por ámbito funcional (máximo ${config.maxScopes} scopes por commit).`,
+    });
+  }
+
+  if (config.enforceCommitMessagePattern && params.stage !== 'PRE_COMMIT') {
+    let pattern: RegExp;
+    try {
+      pattern = new RegExp(config.commitMessagePattern);
+    } catch {
+      pattern = new RegExp(DEFAULT_COMMIT_PATTERN);
+    }
+    const subjects = collectCommitSubjects({
+      git,
+      repoRoot,
+      fromRef: params.fromRef,
+      toRef: params.toRef,
+    });
+    const invalidSubjects = subjects.filter((subject) => !pattern.test(subject));
+    if (invalidSubjects.length > 0) {
+      const sample = invalidSubjects.slice(0, 3).join(' | ');
+      violations.push({
+        code: 'GIT_ATOMICITY_COMMIT_MESSAGE_TRACEABILITY',
+        message:
+          `Git atomicity guard blocked at ${params.stage}: commit messages without traceable pattern detected (${invalidSubjects.length}). sample=[${sample}].`,
+        remediation:
+          'Reescribe los commits para cumplir el patrón de trazabilidad configurado (por ejemplo Conventional Commits).',
+      });
+    }
+  }
+
+  return {
+    enabled: true,
+    allowed: violations.length === 0,
+    violations,
+  };
+};

package/integrations/git/runPlatformGate.ts

@@ -132,6 +132,13 @@ const defaultDependencies: GateDependencies = {
 };
 
 const resolveCurrentBranch = (git: IGitService, repoRoot: string): string | null => {
+  try {
+    const symbolicBranch = git.runGit(['symbolic-ref', '--short', 'HEAD'], repoRoot).trim();
+    if (symbolicBranch.length > 0) {
+      return symbolicBranch;
+    }
+  } catch {
+  }
   try {
     const branch = git.runGit(['rev-parse', '--abbrev-ref', 'HEAD'], repoRoot).trim();
     if (branch.length === 0 || branch === 'HEAD') {