pumuki 6.3.41 → 6.3.43

package/docs/MCP_SERVERS.md

@@ -162,6 +162,8 @@ URI no soportada devuelve `404`.
 ### Catálogo de tools
 
 - `ai_gate_check`
+- `pre_flight_check`
+- `auto_execute_ai_start`
 - `check_sdd_status`
 - `validate_and_fix`
 - `sync_branches`
@@ -198,11 +200,32 @@ URI no soportada devuelve `404`.
 
 - `status`: `ALLOWED|BLOCKED`
 - `stage`
+- `message` (resumen humano corto)
+- `branch`
+- `timestamp`
 - `violations[]`
+- `warnings[]` (por ejemplo rama protegida o upstream ausente)
+- `auto_fixes[]` (remediaciones accionables)
 - `evidence` (kind + age/max-age)
 - `mcp_receipt` (required/kind/path/age para enforcement de PRE_WRITE)
 - `repo_state` (git + lifecycle snapshot)
 
+`pre_flight_check` añade salida de paridad legacy para lectura inmediata:
+
+- `phase`: `GREEN|RED`
+- `message`
+- `instruction`
+- `hints[]`
+
+`auto_execute_ai_start` añade contrato humano estable por iteración:
+
+- `action`: `proceed|ask`
+- `phase`: `GREEN|RED`
+- `message`
+- `instruction`
+- `platforms.force`
+- `confidence_pct`, `reason_code`, `next_action`
+
 Además, cada ejecución de `ai_gate_check` persiste un recibo auditable en:
 
 - `.pumuki/artifacts/mcp-ai-gate-receipt.json`

package/docs/RELEASE_NOTES.md

@@ -5,6 +5,35 @@ Detailed commit history remains available through Git history (`git log` / `git
 
 ## 2026-03 (enterprise hardening updates)
 
+### 2026-03-05 (v6.3.43)
+
+- `pumuki sdd evidence` alinea su salida con el contrato TDD/BDD del gate:
+  - `version: "1"` (antes `1.0`),
+  - `slices[]` generado por defecto con estructura `red/green/refactor`.
+- Compatibilidad de transición mantenida:
+  - el artefacto conserva campos legacy (`scenario_id`, `test_run`, `ai_evidence`) para flujos existentes,
+  - `pumuki sdd state-sync` acepta source evidence `version=1` y `version=1.0`.
+- Evidencia de validación:
+  - `npx --yes tsx@4.21.0 --test integrations/sdd/__tests__/evidenceScaffold.test.ts integrations/sdd/__tests__/stateSync.test.ts integrations/lifecycle/__tests__/cli.test.ts` (`47 pass / 0 fail`)
+  - `npm run -s typecheck` (`PASS`)
+  - smoke real en Flux con CLI local: `pumuki sdd evidence ... --json` -> artefacto `version: "1"` con `slices[]`.
+
+### 2026-03-05 (v6.3.42)
+
+- Modal flotante de bloqueo (macOS) ajustado para legibilidad real:
+  - crecimiento preferente en vertical según contenido,
+  - ancho acotado para evitar diálogos excesivamente horizontales,
+  - tipografía más compacta para causa/solución.
+- Remediación por defecto más accionable en bloqueos:
+  - mensajes enriquecidos para `EVIDENCE_*`, `PRE_PUSH_UPSTREAM_MISSING`, `SDD_SESSION_*`,
+  - más contexto operativo sin truncado agresivo.
+- Ajustes de robustez visual:
+  - wrapping explícito multilínea en campos del modal,
+  - pinning bottom-right estable tras recalcular layout.
+- Evidencia de validación:
+  - `npx --yes tsx@4.21.0 --test scripts/__tests__/framework-menu-system-notifications.test.ts integrations/mcp/__tests__/aiGateCheck.test.ts integrations/mcp/__tests__/autoExecuteAiStart.test.ts integrations/mcp/__tests__/preFlightCheck.test.ts integrations/git/__tests__/runPlatformGate.test.ts integrations/git/__tests__/runPlatformGateOutput.test.ts integrations/git/__tests__/gitAtomicity.test.ts integrations/sdd/__tests__/policy.test.ts integrations/sdd/__tests__/sessionStore.test.ts` (`94 pass / 0 fail`)
+  - `npm run -s typecheck` (`PASS`)
+
 ### 2026-03-05 (v6.3.41)
 
 - UX de notificaciones de bloqueo mejorada para escenarios multi-repo:

package/docs/USAGE.md

@@ -204,6 +204,8 @@ Stage mapping:
 If a scope is empty, the menu prints an explicit operational hint (`Scope vacío`), so `PASS` with zero findings is distinguishable from a clean repository scan.
 
 System notifications (macOS) can be enabled from advanced menu option `31` (persisted in `.pumuki/system-notifications.json`).
+Blocked notifications now use a native Swift floating modal (bottom-right) by default, with AppleScript fallback.
+Override mode with `PUMUKI_MACOS_BLOCKED_DIALOG_MODE=auto|swift-floating|applescript`.
 Custom skills import is available in advanced menu option `33` (writes `/.pumuki/custom-rules.json`).
 Menu-driven audits apply SDD guardrails with the same strict semantics as stage runners (no bypass).
 

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

@@ -7,9 +7,9 @@
 ## Estado actual
 - Plan activo: `docs/seguimiento-activo-pumuki-saas-supermercados.md`
 - Estado del plan: EJECUCION
-- Última task cerrada (`✅`): PUMUKI-131 (issue `#716`, `next_commands[].probe_timeout_ms`).
-- Task activa (`🚧`): PUMUKI-132 (issue `#717`, `next_commands[].probe_kind`).
-- Nuevos pendientes añadidos (`⏳`): ninguno en este bloque inmediato.
+- Última task cerrada (`✅`): PUMUKI-146 (opción 2 UX cerrada: helper Swift nativo para modal flotante abajo-derecha con fallback AppleScript).
+- Task activa (`🚧`): PUMUKI-147 (monitorización post-opción-2 en uso real multi-repo).
+- Nuevos pendientes añadidos (`⏳`): ninguno.
 
 ## Historial resumido
 - Bloque RuralGO cerrado: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`.

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

@@ -1740,7 +1740,7 @@
     - `npx --yes tsx@4.21.0 --test scripts/__tests__/framework-menu-system-notifications.test.ts` -> `13 pass / 0 fail`.
     - `npm run -s typecheck` -> `PASS`.
 
-- 🚧 PUMUKI-139: Monitorizar feedback post-release en consumidores reales (SAAS y RuralGo) y registrar únicamente hallazgos netos nuevos para siguiente corte.
+- ✅ PUMUKI-139: Monitorizar feedback post-release en consumidores reales (SAAS y RuralGo) y registrar únicamente hallazgos netos nuevos para siguiente corte.
   - Alcance:
     - vigilar nuevos bloqueos/regresiones tras `6.3.41`,
     - mantener MDs externos sincronizados por leyenda sin contradicciones,
@@ -1755,3 +1755,122 @@
   - Evidencia (2026-03-05):
     - `npm publish --access public` -> `+ pumuki@6.3.41`.
     - `npm view pumuki version` -> `6.3.41`.
+
+- ✅ PUMUKI-141: Cerrar hallazgo Flux `PUM-001` (autoguía SDD en `SDD_SESSION_MISSING`) con comando asistido y sugerencia concreta.
+  - Resultado implementado:
+    - `integrations/sdd/sessionStore.ts`: soporte real para `pumuki sdd session --open --change=auto`.
+    - `integrations/sdd/policy.ts`: guidance contextual para `SDD_SESSION_MISSING` con `command/fallbackCommand/suggestedChangeId`.
+    - `integrations/lifecycle/cli.ts`: ayuda CLI actualizada (`--change=<change-id|auto>`).
+  - Evidencia (2026-03-05):
+    - `npx --yes tsx@4.21.0 --test integrations/sdd/__tests__/sessionStore.test.ts integrations/sdd/__tests__/policy.test.ts` -> `27 pass / 0 fail`.
+    - `npm run -s typecheck` -> `PASS`.
+
+- ✅ PUMUKI-142: Cerrar hallazgos Flux `PUM-003` + `PUM-004` (DX de bloqueo jerárquico + remediación accionable por scopes).
+  - Resultado implementado:
+    - `integrations/git/runPlatformGateOutput.ts`: resumen jerárquico de bloqueo (`primary`, `next_action`) antes del detalle completo de findings.
+    - `integrations/git/gitAtomicity.ts`: remediación `GIT_ATOMICITY_TOO_MANY_SCOPES` con scopes detectados y ejemplo directo de split de staging.
+    - Tests nuevos:
+      - `integrations/git/__tests__/runPlatformGateOutput.test.ts`
+      - ampliación en `integrations/git/__tests__/gitAtomicity.test.ts`.
+  - Evidencia (2026-03-05):
+    - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/gitAtomicity.test.ts integrations/git/__tests__/runPlatformGateOutput.test.ts` -> `7 pass / 0 fail`.
+    - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/stageRunners.test.ts integrations/lifecycle/__tests__/cli.test.ts` -> `91 pass / 0 fail`.
+    - `npm run -s typecheck` -> `PASS`.
+
+- ✅ PUMUKI-143: Ejecutar siguiente hallazgo Flux `PUM-002` (modo proporcional por riesgo para bloqueos `skills.frontend.*` en cambios low-risk).
+  - Resultado implementado:
+    - `integrations/git/runPlatformGate.ts`:
+      - nuevo soft-enforcement determinista para `PRE_COMMIT` low-risk (`PUMUKI_PRE_COMMIT_SOFT_SKILLS`, on por defecto),
+      - degrada a `WARN` (sin bypass total) findings de coverage skills (`platform-coverage`, `cross-platform-critical`, `scope-compliance`) cuando:
+        - ventana low-risk (`observed_code_paths<=3`),
+        - no hay bloqueantes core reales (`ERROR/CRITICAL`) en findings nativos/TDD/AST/policy/coverage hard.
+    - `integrations/git/__tests__/runPlatformGate.test.ts`:
+      - cobertura RED->GREEN para soft-enforcement en `PRE_COMMIT`.
+  - Evidencia (2026-03-05):
+    - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/runPlatformGate.test.ts` -> `33 pass / 0 fail`.
+    - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/stageRunners.test.ts integrations/sdd/__tests__/sessionStore.test.ts integrations/sdd/__tests__/policy.test.ts integrations/git/__tests__/gitAtomicity.test.ts integrations/git/__tests__/runPlatformGateOutput.test.ts` -> `60 pass / 0 fail`.
+    - `npm run -s typecheck` -> `PASS`.
+  - Alcance:
+    - diseñar criterio determinista de low-risk (copy/docs) sin abrir bypass inseguro,
+    - mantener enforcement fuerte en cambios funcionales reales,
+    - validar con RED->GREEN->REFACTOR y actualizar leyenda del MD de Flux.
+
+- ✅ PUMUKI-144: Monitorizar nuevos hallazgos netos tras cierre completo del backlog Flux (sin reabrir issues ya cerradas).
+  - Resultado:
+    - reapareció gap neto de paridad UX legacy en tools MCP (feedback humano por iteración),
+    - se consolidó como mejora real de producto (no reapertura de `PUM-001..004`).
+
+- ✅ PUMUKI-145: Implementar paridad de feedback humano en tools MCP (`auto_execute_ai_start`, `pre_flight_check`, `ai_gate_check`).
+  - Resultado implementado:
+    - `integrations/mcp/autoExecuteAiStart.ts`: salida humana estable con `phase`, `message`, `instruction` y `platforms.force`.
+    - `integrations/mcp/preFlightCheck.ts`: añade `phase`, `message`, `instruction`, `ast_analysis`, `tdd_status` para lectura directa en chat/tooling.
+    - `integrations/mcp/aiGateCheck.ts`: añade `message`, `timestamp`, `branch`, `warnings`, `auto_fixes` sin romper contrato existente.
+    - Tests ampliados:
+      - `integrations/mcp/__tests__/autoExecuteAiStart.test.ts`
+      - `integrations/mcp/__tests__/preFlightCheck.test.ts`
+      - `integrations/mcp/__tests__/aiGateCheck.test.ts`
+  - Evidencia (2026-03-05):
+    - `npx --yes tsx@4.21.0 --test integrations/mcp/__tests__/aiGateCheck.test.ts integrations/mcp/__tests__/preFlightCheck.test.ts integrations/mcp/__tests__/autoExecuteAiStart.test.ts` -> `12 pass / 0 fail`.
+    - `npm run -s typecheck` -> `PASS`.
+
+- ✅ PUMUKI-146: Cerrar opción 2 UX de notificación bloqueante (modal flotante no intrusiva + posicionamiento consistente para no tapar el centro).
+  - Resultado implementado:
+    - `scripts/framework-menu-system-notifications-lib.ts`:
+      - helper nativo Swift para diálogo bloqueante flotante (esquina inferior derecha),
+      - persistencia runtime del script en `.pumuki/runtime/pumuki-blocked-dialog.swift`,
+      - selector de modo `PUMUKI_MACOS_BLOCKED_DIALOG_MODE=auto|swift-floating|applescript`,
+      - fallback automático a AppleScript si el helper Swift falla.
+    - `scripts/__tests__/framework-menu-system-notifications.test.ts`:
+      - cobertura para modo por defecto (Swift), modo forzado AppleScript y fallback Swift->AppleScript.
+    - `docs/USAGE.md`: contrato operativo del nuevo modo de diálogo.
+  - Evidencia (2026-03-05):
+    - `npx --yes tsx@4.21.0 --test scripts/__tests__/framework-menu-system-notifications.test.ts` -> `15 pass / 0 fail`.
+    - `npm run -s typecheck` -> `PASS`.
+
+- ✅ PUMUKI-147: Monitorizar feedback real post-opción-2 (legibilidad, anti-spam, foco no intrusivo) y cerrar ajustes finos si aparece regresión.
+  - Alcance:
+    - validar comportamiento en múltiples repos abiertos simultáneamente,
+    - confirmar que acciones de diálogo (`Desactivar`, `Silenciar 30 min`, `Mantener activas`) se mantienen consistentes,
+    - registrar solo hallazgos netos nuevos antes del siguiente corte release.
+  - Ajuste aplicado (2026-03-05):
+    - pinning reforzado de posición del helper Swift: selección de pantalla por cursor, posicionamiento explícito bottom-right y repinning tras `orderFront` para evitar recentrado.
+    - UI responsive del modal flotante: ancho/alto dinámicos según longitud real de `title/cause/remediation`, con límites por pantalla y autoajuste de layout para evitar texto truncado.
+    - tuning visual adicional: ancho máximo reducido, crecimiento preferente en vertical y tipografía compacta para evitar modales excesivamente anchos/bastos en textos largos.
+  - Evidencia:
+    - `npx --yes tsx@4.21.0 --test scripts/__tests__/framework-menu-system-notifications.test.ts` -> `15 pass / 0 fail`.
+    - `npm run -s typecheck` -> `PASS`.
+    - smoke manual con payload largo (`/tmp/pumuki_modal_smoke.ts`) -> `{"delivered":true,"reason":"delivered"}`.
+
+- ✅ PUMUKI-148: Ejecutar verificación UX final en entorno real multi-proyecto (notificación + modal) y preparar corte de release sin regresiones.
+  - Alcance:
+    - validar que textos largos no truncen en causa/solución,
+    - validar consistencia visual de acciones del modal en distintas resoluciones,
+    - confirmar que no hay regresiones en fallback AppleScript.
+  - Avance (2026-03-05):
+    - patrón de remediación enriquecido por defecto en bloqueos (`EVIDENCE_STALE`, `PRE_PUSH_UPSTREAM_MISSING`, `SDD_SESSION_*`, `BACKEND_AVOID_EXPLICIT_ANY`) para mantener mensajes accionables y humanos en modal/notificación.
+    - longitud de remediación ampliada (`max 220`) para preservar pasos útiles sin recorte agresivo.
+    - validación manual de modales de prueba (corto/medio/largo/extremo) en helper Swift flotante con rendering consistente y sin regresión de acciones (`Desactivar`, `Silenciar 30 min`, `Mantener activas`).
+
+- ✅ PUMUKI-149: Preparar corte release del bloque UX-notificaciones y ejecutar upgrade/smoke en consumidores (`SAAS`, `RuralGo`, `Flux_training`).
+  - Alcance:
+    - cerrar changelog/release notes del bloque `PUMUKI-145..148`,
+    - publicar versión npm con trazabilidad,
+    - ejecutar `install/update` + smoke mínimo en los tres repos consumidores,
+    - actualizar estado final en MDs externos por leyenda.
+  - Resultado (2026-03-05):
+    - publicación npm completada: `pumuki@6.3.42`.
+    - upgrade aplicado con `pumuki install` en:
+      - `SAAS:APP_SUPERMERCADOS` (`lifecycle_version=6.3.42`)
+      - `R_GO` (`lifecycle_version=6.3.42`)
+      - `Flux_training` (`lifecycle_version=6.3.42`)
+    - smoke de salud post-upgrade en 3/3 consumidores:
+      - `doctor_issues=0`
+      - `openspec_compatible=true`
+      - `session_active=true`
+
+- 🚧 PUMUKI-150: Ejecutar siguiente pendiente real en backlog externo (Flux `PUM-005`) y cerrar incidencia de `pumuki sdd evidence` con contrato v1 compatible con gate TDD.
+  - Alcance:
+    - reproducir `PUM-005` con evidencia local controlada,
+    - aplicar fix mínimo en core (`sdd evidence` -> `version=\"1\"` + `slices[]`),
+    - validar RED->GREEN con smoke en `Flux_training`,
+    - actualizar leyenda en `docs/BUGS_Y_MEJORAS_PUMUKI.md` (Flux) sin tocar código del consumer.

package/integrations/git/gitAtomicity.ts

@@ -265,11 +265,19 @@ export const evaluateGitAtomicity = (params: {
       .filter((scopeKey) => scopeKey.length > 0)
   );
   if (scopeKeys.size > config.maxScopes) {
+    const sortedScopes = [...scopeKeys].sort();
+    const suggestedScopeAdds = sortedScopes
+      .slice(0, Math.max(1, Math.min(config.maxScopes + 1, 3)))
+      .map((scope) => `git add ${scope}/`)
+      .join(' && ');
     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).`,
+      remediation:
+        `Agrupa cambios por ámbito funcional (máximo ${config.maxScopes} scopes por commit). ` +
+        `scopes_detectados=[${sortedScopes.join(', ')}]. ` +
+        `Sugerencia: git restore --staged . && ${suggestedScopeAdds} && git commit -m "<tipo>: <scope>".`,
     });
   }
 

package/integrations/git/runPlatformGate.ts

@@ -742,6 +742,28 @@ const shouldBlockFromFinding = (finding: Finding | undefined): boolean => {
   return finding.severity === 'ERROR' || finding.severity === 'CRITICAL';
 };
 
+const toSoftPreCommitSkillsFinding = (params: {
+  finding: Finding | undefined;
+  enabled: boolean;
+  observedCodePaths: ReadonlyArray<string>;
+}): Finding | undefined => {
+  if (!params.finding) {
+    return undefined;
+  }
+  if (!params.enabled || !shouldBlockFromFinding(params.finding)) {
+    return params.finding;
+  }
+  return {
+    ...params.finding,
+    severity: 'WARN',
+    code: `${params.finding.code}_SOFT_PRECOMMIT`,
+    message:
+      `${params.finding.message} ` +
+      `Soft-enforced at PRE_COMMIT for low-risk scope (observed_code_paths=${params.observedCodePaths.length}). ` +
+      'Strict enforcement remains active at PRE_PUSH/CI.',
+  };
+};
+
 export async function runPlatformGate(params: {
   policy: GatePolicy;
   auditMode?: 'gate' | 'engine';
@@ -813,6 +835,7 @@ export async function runPlatformGate(params: {
     git,
   });
   const filesScanned = countScannedFilesFromFacts(facts);
+  const observedCodePaths = collectObservedCodePathsFromFacts(facts);
 
   const {
     detectedPlatforms,
@@ -1002,15 +1025,49 @@ export async function runPlatformGate(params: {
   const hasTddBddBlockingFinding = tddBddEvaluation.findings.some(
     (finding) => finding.severity === 'ERROR' || finding.severity === 'CRITICAL'
   );
+  const hasNativeBlockingFinding = findings.some(
+    (finding) => finding.severity === 'ERROR' || finding.severity === 'CRITICAL'
+  );
+  const preCommitSoftSkillsEnabled = process.env.PUMUKI_PRE_COMMIT_SOFT_SKILLS !== '0';
+  const lowRiskPreCommitWindow = observedCodePaths.length > 0 && observedCodePaths.length <= 3;
+  const shouldSoftEnforceSkillsFindings =
+    params.policy.stage === 'PRE_COMMIT'
+    && preCommitSoftSkillsEnabled
+    && lowRiskPreCommitWindow
+    && !sddBlockingFinding
+    && !degradedModeBlocks
+    && !shouldBlockFromFinding(policyAsCodeBlockingFinding)
+    && !shouldBlockFromFinding(unsupportedSkillsMappingFinding)
+    && !shouldBlockFromFinding(coverageBlockingFinding)
+    && !shouldBlockFromFinding(activeRulesEmptyForCodeChangesFinding)
+    && !shouldBlockFromFinding(iosTestsQualityFinding)
+    && !shouldBlockFromFinding(astIntelligenceDualFinding)
+    && !hasTddBddBlockingFinding
+    && !hasNativeBlockingFinding;
+  const effectivePlatformSkillsCoverageFinding = toSoftPreCommitSkillsFinding({
+    finding: platformSkillsCoverageFinding,
+    enabled: shouldSoftEnforceSkillsFindings,
+    observedCodePaths,
+  });
+  const effectiveCrossPlatformCriticalFinding = toSoftPreCommitSkillsFinding({
+    finding: crossPlatformCriticalFinding,
+    enabled: shouldSoftEnforceSkillsFindings,
+    observedCodePaths,
+  });
+  const effectiveSkillsScopeComplianceFinding = toSoftPreCommitSkillsFinding({
+    finding: skillsScopeComplianceFinding,
+    enabled: shouldSoftEnforceSkillsFindings,
+    observedCodePaths,
+  });
   const effectiveFindings = sddBlockingFinding
     ? [
       sddBlockingFinding,
       ...(degradedModeFinding ? [degradedModeFinding] : []),
       ...(policyAsCodeBlockingFinding ? [policyAsCodeBlockingFinding] : []),
       ...(unsupportedSkillsMappingFinding ? [unsupportedSkillsMappingFinding] : []),
-      ...(platformSkillsCoverageFinding ? [platformSkillsCoverageFinding] : []),
-      ...(crossPlatformCriticalFinding ? [crossPlatformCriticalFinding] : []),
-      ...(skillsScopeComplianceFinding ? [skillsScopeComplianceFinding] : []),
+      ...(effectivePlatformSkillsCoverageFinding ? [effectivePlatformSkillsCoverageFinding] : []),
+      ...(effectiveCrossPlatformCriticalFinding ? [effectiveCrossPlatformCriticalFinding] : []),
+      ...(effectiveSkillsScopeComplianceFinding ? [effectiveSkillsScopeComplianceFinding] : []),
       ...(activeRulesEmptyForCodeChangesFinding ? [activeRulesEmptyForCodeChangesFinding] : []),
       ...(iosTestsQualityFinding ? [iosTestsQualityFinding] : []),
       ...(astIntelligenceDualFinding ? [astIntelligenceDualFinding] : []),
@@ -1019,9 +1076,9 @@ export async function runPlatformGate(params: {
       ...findings,
     ]
     : unsupportedSkillsMappingFinding
-      || platformSkillsCoverageFinding
-      || crossPlatformCriticalFinding
-      || skillsScopeComplianceFinding
+      || effectivePlatformSkillsCoverageFinding
+      || effectiveCrossPlatformCriticalFinding
+      || effectiveSkillsScopeComplianceFinding
       || activeRulesEmptyForCodeChangesFinding
       || iosTestsQualityFinding
       || astIntelligenceDualFinding
@@ -1033,9 +1090,9 @@ export async function runPlatformGate(params: {
         ...(degradedModeFinding ? [degradedModeFinding] : []),
         ...(policyAsCodeBlockingFinding ? [policyAsCodeBlockingFinding] : []),
         ...(unsupportedSkillsMappingFinding ? [unsupportedSkillsMappingFinding] : []),
-        ...(platformSkillsCoverageFinding ? [platformSkillsCoverageFinding] : []),
-        ...(crossPlatformCriticalFinding ? [crossPlatformCriticalFinding] : []),
-        ...(skillsScopeComplianceFinding ? [skillsScopeComplianceFinding] : []),
+        ...(effectivePlatformSkillsCoverageFinding ? [effectivePlatformSkillsCoverageFinding] : []),
+        ...(effectiveCrossPlatformCriticalFinding ? [effectiveCrossPlatformCriticalFinding] : []),
+        ...(effectiveSkillsScopeComplianceFinding ? [effectiveSkillsScopeComplianceFinding] : []),
         ...(activeRulesEmptyForCodeChangesFinding ? [activeRulesEmptyForCodeChangesFinding] : []),
         ...(iosTestsQualityFinding ? [iosTestsQualityFinding] : []),
         ...(astIntelligenceDualFinding ? [astIntelligenceDualFinding] : []),
@@ -1049,15 +1106,15 @@ export async function runPlatformGate(params: {
   const baseGateOutcome =
     sddBlockingFinding ||
     degradedModeBlocks ||
-    policyAsCodeBlockingFinding ||
-    unsupportedSkillsMappingFinding ||
-    platformSkillsCoverageFinding ||
-    crossPlatformCriticalFinding ||
-    skillsScopeComplianceFinding ||
-    activeRulesEmptyForCodeChangesFinding ||
-    iosTestsQualityFinding ||
+    shouldBlockFromFinding(policyAsCodeBlockingFinding) ||
+    shouldBlockFromFinding(unsupportedSkillsMappingFinding) ||
+    shouldBlockFromFinding(effectivePlatformSkillsCoverageFinding) ||
+    shouldBlockFromFinding(effectiveCrossPlatformCriticalFinding) ||
+    shouldBlockFromFinding(effectiveSkillsScopeComplianceFinding) ||
+    shouldBlockFromFinding(activeRulesEmptyForCodeChangesFinding) ||
+    shouldBlockFromFinding(iosTestsQualityFinding) ||
     hasAstIntelligenceBlockingFinding ||
-    coverageBlockingFinding ||
+    shouldBlockFromFinding(coverageBlockingFinding) ||
     hasTddBddBlockingFinding
       ? 'BLOCK'
       : decision.outcome;

package/integrations/git/runPlatformGateOutput.ts

@@ -1,5 +1,53 @@
 import type { Finding } from '../../core/gate/Finding';
 
+const BLOCK_NEXT_ACTION_BY_CODE: Readonly<Record<string, string>> = {
+  SDD_SESSION_MISSING:
+    'npx --yes --package pumuki@latest pumuki sdd session --open --change=auto',
+  SDD_SESSION_INVALID:
+    'npx --yes --package pumuki@latest pumuki sdd session --refresh --ttl-minutes=90',
+  PRE_PUSH_UPSTREAM_MISSING:
+    'git push --set-upstream origin <branch>',
+  PRE_PUSH_UPSTREAM_MISALIGNED:
+    'git branch --unset-upstream && git push --set-upstream origin <branch>',
+  EVIDENCE_STALE:
+    'npx --yes --package pumuki@latest pumuki-pre-commit',
+  EVIDENCE_BRANCH_MISMATCH:
+    'npx --yes --package pumuki@latest pumuki-pre-commit',
+  GIT_ATOMICITY_TOO_MANY_FILES:
+    'git restore --staged . && separa cambios en commits más pequeños',
+  GIT_ATOMICITY_TOO_MANY_SCOPES:
+    'git restore --staged . && git add <scope>/ && git commit -m "<tipo>: <scope>"',
+};
+
+const severityWeight = (severity: string): number => {
+  switch (severity.toUpperCase()) {
+    case 'CRITICAL':
+      return 5;
+    case 'ERROR':
+      return 4;
+    case 'WARN':
+      return 3;
+    case 'INFO':
+      return 2;
+    default:
+      return 1;
+  }
+};
+
+const resolvePrimaryFinding = (findings: ReadonlyArray<Finding>): Finding => {
+  let primary = findings[0];
+  for (const finding of findings.slice(1)) {
+    if (!primary) {
+      primary = finding;
+      continue;
+    }
+    if (severityWeight(finding.severity) > severityWeight(primary.severity)) {
+      primary = finding;
+    }
+  }
+  return primary ?? findings[0]!;
+};
+
 const normalizeAnchorLine = (lines: Finding['lines']): number => {
   if (Array.isArray(lines)) {
     const candidates = lines
@@ -43,6 +91,17 @@ const formatFinding = (finding: Finding): string => {
 };
 
 export const printGateFindings = (findings: ReadonlyArray<Finding>): void => {
+  if (findings.length === 0) {
+    return;
+  }
+  const primary = resolvePrimaryFinding(findings);
+  const nextAction =
+    BLOCK_NEXT_ACTION_BY_CODE[primary.code]
+    ?? 'Corrige el bloqueante primario y vuelve a ejecutar el mismo comando.';
+  process.stdout.write(
+    `[pumuki][block-summary] primary=${primary.code} severity=${primary.severity.toUpperCase()} rule=${primary.ruleId}\n`
+  );
+  process.stdout.write(`[pumuki][block-summary] next_action=${nextAction}\n`);
   for (const finding of findings) {
     process.stdout.write(`${formatFinding(finding)}\n`);
   }

package/integrations/lifecycle/cli.ts

@@ -191,7 +191,7 @@ Pumuki lifecycle commands:
   pumuki policy reconcile [--strict] [--json]
   pumuki sdd status [--json]
   pumuki sdd validate [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--json]
-  pumuki sdd session --open --change=<change-id> [--ttl-minutes=<n>] [--json]
+  pumuki sdd session --open --change=<change-id|auto> [--ttl-minutes=<n>] [--json]
   pumuki sdd session --refresh [--ttl-minutes=<n>] [--json]
   pumuki sdd session --close [--json]
   pumuki sdd sync-docs [--change=<change-id>] [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--task=<task-id>] [--from-evidence=<path>] [--dry-run] [--json]
@@ -2417,7 +2417,7 @@ export const runLifecycleCli = async (
             }
           }
           const shouldEvaluateAiGate = result.stage === 'PRE_WRITE';
-          let aiGate = shouldEvaluateAiGate
+          let aiGate: ReturnType<typeof evaluateAiGate> | null = shouldEvaluateAiGate
             ? runEnterpriseAiGateCheck({
               repoRoot: process.cwd(),
               stage: result.stage,

package/integrations/mcp/aiGateCheck.ts

@@ -1,5 +1,17 @@
 import { evaluateAiGate, type AiGateStage } from '../gate/evaluateAiGate';
 
+const AUTO_FIX_BY_CODE: Readonly<Record<string, string>> = {
+  EVIDENCE_MISSING: 'Ejecuta una auditoría para generar .ai_evidence.json.',
+  EVIDENCE_INVALID: 'Regenera .ai_evidence.json y vuelve a evaluar.',
+  EVIDENCE_STALE: 'Refresca evidencia antes de continuar.',
+  EVIDENCE_BRANCH_MISMATCH: 'Regenera evidencia en la rama actual.',
+  EVIDENCE_REPO_ROOT_MISMATCH: 'Regenera evidencia desde este repositorio.',
+  PRE_PUSH_UPSTREAM_MISSING: 'Ejecuta git push --set-upstream origin <branch>.',
+  GITFLOW_PROTECTED_BRANCH: 'Crea una rama feature/* y mueve el trabajo allí.',
+};
+
+const PROTECTED_BRANCHES = new Set(['main', 'master', 'develop', 'dev']);
+
 export type EnterpriseAiGateCheckResult = {
   tool: 'ai_gate_check';
   dryRun: true;
@@ -8,9 +20,14 @@ export type EnterpriseAiGateCheckResult = {
   result: {
     allowed: ReturnType<typeof evaluateAiGate>['allowed'];
     status: ReturnType<typeof evaluateAiGate>['status'];
+    timestamp: string | null;
+    branch: string | null;
+    message: string;
     stage: ReturnType<typeof evaluateAiGate>['stage'];
     policy: ReturnType<typeof evaluateAiGate>['policy'];
     violations: ReturnType<typeof evaluateAiGate>['violations'];
+    warnings: ReadonlyArray<string>;
+    auto_fixes: ReadonlyArray<string>;
     evidence: ReturnType<typeof evaluateAiGate>['evidence'];
     mcp_receipt: ReturnType<typeof evaluateAiGate>['mcp_receipt'];
     skills_contract: ReturnType<typeof evaluateAiGate>['skills_contract'];
@@ -68,6 +85,48 @@ const buildConsistencyHint = (
   };
 };
 
+const buildWarnings = (evaluation: ReturnType<typeof evaluateAiGate>): ReadonlyArray<string> => {
+  const warnings: string[] = [];
+  const currentBranch = evaluation.repo_state.git.branch;
+  if (typeof currentBranch === 'string' && PROTECTED_BRANCHES.has(currentBranch.toLowerCase())) {
+    warnings.push(
+      `ON_PROTECTED_BRANCH: Estás en '${currentBranch}'. Crea una rama feature/* antes de continuar.`
+    );
+  }
+  if (evaluation.stage === 'PRE_PUSH' && !evaluation.repo_state.git.upstream) {
+    warnings.push('NO_UPSTREAM: Configura upstream con git push --set-upstream origin <branch>.');
+  }
+  return warnings;
+};
+
+const buildAutoFixes = (evaluation: ReturnType<typeof evaluateAiGate>): ReadonlyArray<string> => {
+  const fixes: string[] = [];
+  const emittedCodes = new Set<string>();
+  for (const violation of evaluation.violations) {
+    if (emittedCodes.has(violation.code)) {
+      continue;
+    }
+    const fix = AUTO_FIX_BY_CODE[violation.code];
+    if (!fix) {
+      continue;
+    }
+    fixes.push(fix);
+    emittedCodes.add(violation.code);
+  }
+  return fixes;
+};
+
+const buildMessage = (evaluation: ReturnType<typeof evaluateAiGate>): string => {
+  if (evaluation.allowed) {
+    return `✅ Gate ${evaluation.stage} ALLOWED.`;
+  }
+  const firstViolation = evaluation.violations[0];
+  if (!firstViolation) {
+    return `🔴 Gate ${evaluation.stage} BLOCKED.`;
+  }
+  return `🔴 ${firstViolation.code}: ${firstViolation.message}`;
+};
+
 export const runEnterpriseAiGateCheck = (params: {
   repoRoot: string;
   stage: AiGateStage;
@@ -82,6 +141,11 @@ export const runEnterpriseAiGateCheck = (params: {
     stage: params.stage,
     requireMcpReceipt: params.requireMcpReceipt ?? false,
   });
+  const branch = evaluation.repo_state.git.branch;
+  const timestamp = evaluation.evidence.source.generated_at;
+  const warnings = buildWarnings(evaluation);
+  const autoFixes = buildAutoFixes(evaluation);
+  const message = buildMessage(evaluation);
 
   return {
     tool: 'ai_gate_check',
@@ -91,9 +155,14 @@ export const runEnterpriseAiGateCheck = (params: {
     result: {
       allowed: evaluation.allowed,
       status: evaluation.status,
+      timestamp,
+      branch,
+      message,
       stage: evaluation.stage,
       policy: evaluation.policy,
       violations: evaluation.violations,
+      warnings,
+      auto_fixes: autoFixes,
       evidence: evaluation.evidence,
       mcp_receipt: evaluation.mcp_receipt,
       skills_contract: evaluation.skills_contract,