pumuki 6.3.37 → 6.3.39

package/integrations/lifecycle/hookManager.ts

@@ -16,6 +16,16 @@ export type HookUninstallResult = {
   changedHooks: ReadonlyArray<PumukiManagedHook>;
 };
 
+export type PumukiHooksDirectoryResolutionSource =
+  | 'git-rev-parse'
+  | 'git-config'
+  | 'default';
+
+export type PumukiHooksDirectoryResolution = {
+  path: string;
+  source: PumukiHooksDirectoryResolutionSource;
+};
+
 const HOOK_FILE_MODE = 0o755;
 
 const resolveGitPath = (repoRoot: string, gitPathTarget: string): string | null => {
@@ -34,8 +44,82 @@ const resolveGitPath = (repoRoot: string, gitPathTarget: string): string | null
   }
 };
 
+const readCoreHooksPathFromGitConfig = (repoRoot: string): string | null => {
+  const configPath = join(repoRoot, '.git', 'config');
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  let contents = '';
+  try {
+    contents = readFileSync(configPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  let inCoreSection = false;
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith(';') || line.startsWith('#')) {
+      continue;
+    }
+
+    if (line.startsWith('[') && line.endsWith(']')) {
+      inCoreSection = /^\[core\]$/i.test(line);
+      continue;
+    }
+
+    if (!inCoreSection) {
+      continue;
+    }
+
+    const match = /^hookspath\s*=\s*(.+)$/i.exec(line);
+    if (!match) {
+      continue;
+    }
+
+    let hooksPath = match[1]?.trim() ?? '';
+    if (hooksPath.startsWith('"') && hooksPath.endsWith('"')) {
+      hooksPath = hooksPath.slice(1, -1);
+    }
+    if (hooksPath.length === 0) {
+      continue;
+    }
+    return hooksPath;
+  }
+
+  return null;
+};
+
+export const resolvePumukiHooksDirectory = (
+  repoRoot: string
+): PumukiHooksDirectoryResolution => {
+  const gitPathHooks = resolveGitPath(repoRoot, 'hooks');
+  if (gitPathHooks) {
+    return {
+      path: gitPathHooks,
+      source: 'git-rev-parse',
+    };
+  }
+
+  const hooksPathFromConfig = readCoreHooksPathFromGitConfig(repoRoot);
+  if (hooksPathFromConfig) {
+    return {
+      path: isAbsolute(hooksPathFromConfig)
+        ? hooksPathFromConfig
+        : resolve(repoRoot, hooksPathFromConfig),
+      source: 'git-config',
+    };
+  }
+
+  return {
+    path: join(repoRoot, '.git', 'hooks'),
+    source: 'default',
+  };
+};
+
 const resolveHooksDirectory = (repoRoot: string): string =>
-  resolveGitPath(repoRoot, 'hooks') ?? join(repoRoot, '.git', 'hooks');
+  resolvePumukiHooksDirectory(repoRoot).path;
 
 const resolveHookPath = (repoRoot: string, hook: PumukiManagedHook): string =>
   join(resolveHooksDirectory(repoRoot), hook);

package/integrations/lifecycle/packageInfo.ts

@@ -1,5 +1,31 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import packageJson from '../../package.json';
 
-export const getCurrentPumukiVersion = (): string => packageJson.version;
+const readConsumerInstalledVersion = (repoRoot: string): string | null => {
+  const packagePath = join(repoRoot, 'node_modules', packageJson.name, 'package.json');
+  if (!existsSync(packagePath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(packagePath, 'utf8')) as { version?: unknown };
+    return typeof parsed.version === 'string' && parsed.version.trim().length > 0
+      ? parsed.version.trim()
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+export const getCurrentPumukiVersion = (params?: { repoRoot?: string }): string => {
+  const repoRoot = params?.repoRoot;
+  if (typeof repoRoot === 'string' && repoRoot.trim().length > 0) {
+    const installedVersion = readConsumerInstalledVersion(repoRoot.trim());
+    if (installedVersion) {
+      return installedVersion;
+    }
+  }
+  return packageJson.version;
+};
 
 export const getCurrentPumukiPackageName = (): string => packageJson.name;

package/integrations/lifecycle/status.ts

@@ -1,4 +1,4 @@
-import { getPumukiHooksStatus } from './hookManager';
+import { getPumukiHooksStatus, resolvePumukiHooksDirectory } from './hookManager';
 import { LifecycleGitService, type ILifecycleGitService } from './gitService';
 import { getCurrentPumukiVersion } from './packageInfo';
 import {
@@ -12,6 +12,8 @@ export type LifecycleStatus = {
   packageVersion: string;
   lifecycleState: LifecycleState;
   hookStatus: ReturnType<typeof getPumukiHooksStatus>;
+  hooksDirectory: string;
+  hooksDirectoryResolution: 'git-rev-parse' | 'git-config' | 'default';
   trackedNodeModulesCount: number;
   policyValidation: LifecyclePolicyValidationSnapshot;
 };
@@ -23,13 +25,16 @@ export const readLifecycleStatus = (params?: {
   const git = params?.git ?? new LifecycleGitService();
   const cwd = params?.cwd ?? process.cwd();
   const repoRoot = git.resolveRepoRoot(cwd);
+  const hooksDirectory = resolvePumukiHooksDirectory(repoRoot);
   const trackedNodeModulesCount = git.trackedNodeModulesPaths(repoRoot).length;
 
   return {
     repoRoot,
-    packageVersion: getCurrentPumukiVersion(),
+    packageVersion: getCurrentPumukiVersion({ repoRoot }),
     lifecycleState: readLifecycleState(git, repoRoot),
     hookStatus: getPumukiHooksStatus(repoRoot),
+    hooksDirectory: hooksDirectory.path,
+    hooksDirectoryResolution: hooksDirectory.source,
     trackedNodeModulesCount,
     policyValidation: readLifecyclePolicyValidationSnapshot(repoRoot),
   };

package/integrations/mcp/autoExecuteAiStart.ts

@@ -0,0 +1,116 @@
+import { evaluateAiGate, type AiGateStage, type AiGateViolation } from '../gate/evaluateAiGate';
+
+type AutoExecuteAction = 'proceed' | 'ask';
+
+type AutoExecuteNextAction = {
+  kind: 'info' | 'run_command';
+  message: string;
+  command?: string;
+};
+
+const isEvidenceCode = (code: string): boolean =>
+  code === 'EVIDENCE_MISSING' || code === 'EVIDENCE_INVALID' || code === 'EVIDENCE_STALE';
+
+const confidenceFromViolation = (violationCode: string | null): number => {
+  if (!violationCode) {
+    return 90;
+  }
+  if (isEvidenceCode(violationCode)) {
+    return 65;
+  }
+  if (violationCode === 'GITFLOW_PROTECTED_BRANCH') {
+    return 40;
+  }
+  return 50;
+};
+
+const nextActionFromViolation = (violation: AiGateViolation | undefined): AutoExecuteNextAction => {
+  if (!violation) {
+    return {
+      kind: 'info',
+      message: 'Gate listo. Puedes continuar con implementación.',
+    };
+  }
+  switch (violation.code) {
+    case 'EVIDENCE_MISSING':
+    case 'EVIDENCE_INVALID':
+    case 'EVIDENCE_STALE':
+      return {
+        kind: 'run_command',
+        message: 'Refresca evidencia y vuelve a evaluar PRE_WRITE.',
+        command: 'npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json',
+      };
+    case 'GITFLOW_PROTECTED_BRANCH':
+      return {
+        kind: 'run_command',
+        message: 'Cambia a una rama feature/* antes de continuar.',
+        command: 'git checkout -b feature/<descripcion-kebab-case>',
+      };
+    default:
+      return {
+        kind: 'info',
+        message: 'Corrige la violación bloqueante y vuelve a ejecutar auto_execute_ai_start.',
+      };
+  }
+};
+
+export type EnterpriseAutoExecuteAiStartResult = {
+  tool: 'auto_execute_ai_start';
+  dryRun: true;
+  executed: true;
+  success: boolean;
+  result: {
+    action: AutoExecuteAction;
+    confidence_pct: number;
+    reason_code: string;
+    next_action: AutoExecuteNextAction;
+    gate: {
+      stage: ReturnType<typeof evaluateAiGate>['stage'];
+      status: ReturnType<typeof evaluateAiGate>['status'];
+      allowed: ReturnType<typeof evaluateAiGate>['allowed'];
+      violations_count: number;
+    };
+  };
+};
+
+export const runEnterpriseAutoExecuteAiStart = (params: {
+  repoRoot: string;
+  stage?: AiGateStage;
+  requireMcpReceipt?: boolean;
+}): EnterpriseAutoExecuteAiStartResult => {
+  const stage = params.stage ?? 'PRE_WRITE';
+  const evaluation = evaluateAiGate({
+    repoRoot: params.repoRoot,
+    stage,
+    requireMcpReceipt: params.requireMcpReceipt ?? false,
+  });
+  const firstViolation = evaluation.violations[0];
+  const reasonCode = firstViolation?.code ?? 'READY';
+  const action: AutoExecuteAction = evaluation.allowed ? 'proceed' : 'ask';
+  const confidencePct = confidenceFromViolation(firstViolation?.code ?? null);
+  const nextAction = evaluation.allowed
+    ? {
+      kind: 'info' as const,
+      message: 'Gate en verde. Continúa con la implementación.',
+    }
+    : nextActionFromViolation(firstViolation);
+
+  return {
+    tool: 'auto_execute_ai_start',
+    dryRun: true,
+    executed: true,
+    success: true,
+    result: {
+      action,
+      confidence_pct: confidencePct,
+      reason_code: reasonCode,
+      next_action: nextAction,
+      gate: {
+        stage: evaluation.stage,
+        status: evaluation.status,
+        allowed: evaluation.allowed,
+        violations_count: evaluation.violations.length,
+      },
+    },
+  };
+};

package/integrations/mcp/enterpriseServer.ts

@@ -9,6 +9,8 @@ import { evaluateSddPolicy, readSddStatus } from '../sdd';
 import type { SddStage } from '../sdd';
 import { toStatusPayload } from './evidencePayloads';
 import { runEnterpriseAiGateCheck } from './aiGateCheck';
+import { runEnterprisePreFlightCheck } from './preFlightCheck';
+import { runEnterpriseAutoExecuteAiStart } from './autoExecuteAiStart';
 import { writeMcpAiGateReceipt } from './aiGateReceipt';
 
 export interface EnterpriseServerOptions {
@@ -73,6 +75,8 @@ const ENTERPRISE_RESOURCE_DESCRIPTORS: ReadonlyArray<{
 
 const ENTERPRISE_TOOLS = [
   'ai_gate_check',
+  'pre_flight_check',
+  'auto_execute_ai_start',
   'check_sdd_status',
   'validate_and_fix',
   'sync_branches',
@@ -92,6 +96,18 @@ const ENTERPRISE_TOOL_DESCRIPTORS: ReadonlyArray<{
     mutating: false,
     safeByDefault: true,
   },
+  {
+    name: 'pre_flight_check',
+    description: 'Runs pre-flight gate checks with actionable hints using the same AI gate evaluator.',
+    mutating: false,
+    safeByDefault: true,
+  },
+  {
+    name: 'auto_execute_ai_start',
+    description: 'Returns actionable decision to continue or ask user with stable confidence and next_action.',
+    mutating: false,
+    safeByDefault: true,
+  },
   {
     name: 'check_sdd_status',
     description: 'Evaluates SDD/OpenSpec policy for a stage without changing repository state.',
@@ -378,6 +394,46 @@ const executeEnterpriseTool = (
         },
       };
     }
+    case 'pre_flight_check': {
+      const stage = toSddStage(args.stage, 'PRE_COMMIT');
+      const execution = runEnterprisePreFlightCheck({
+        repoRoot,
+        stage,
+      });
+      const receiptWrite = writeMcpAiGateReceipt({
+        repoRoot,
+        stage: execution.result.stage,
+        status: execution.result.status,
+        allowed: execution.result.allowed,
+      });
+      return {
+        name: toolName,
+        success: execution.success,
+        dryRun: execution.dryRun,
+        executed: execution.executed,
+        data: {
+          ...execution.result,
+          receipt: {
+            path: receiptWrite.path,
+            issued_at: receiptWrite.receipt.issued_at,
+          },
+        },
+      };
+    }
+    case 'auto_execute_ai_start': {
+      const stage = toSddStage(args.stage, 'PRE_WRITE');
+      const execution = runEnterpriseAutoExecuteAiStart({
+        repoRoot,
+        stage,
+      });
+      return {
+        name: toolName,
+        success: execution.success,
+        dryRun: execution.dryRun,
+        executed: execution.executed,
+        data: execution.result,
+      };
+    }
     case 'check_sdd_status': {
       const stage = toSddStage(args.stage, 'PRE_COMMIT');
       let evaluation: ReturnType<typeof evaluateSddPolicy>;

package/integrations/mcp/preFlightCheck.ts

@@ -0,0 +1,108 @@
+import { evaluateAiGate, type AiGateStage, type AiGateViolation } from '../gate/evaluateAiGate';
+
+const ACTIONABLE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
+  EVIDENCE_MISSING: 'Ejecuta una auditoría (1/2/3/4) para regenerar .ai_evidence.json.',
+  EVIDENCE_INVALID: 'Regenera .ai_evidence.json desde una opción de auditoría.',
+  EVIDENCE_STALE: 'Refresca evidencia antes de continuar con commit/push.',
+  EVIDENCE_TIMESTAMP_INVALID: 'Regenera evidencia para obtener un timestamp válido.',
+  EVIDENCE_GATE_BLOCKED: 'Corrige primero las violaciones bloqueantes y vuelve a auditar.',
+  EVIDENCE_REPO_ROOT_MISMATCH: 'Regenera evidencia desde este mismo repositorio.',
+  EVIDENCE_BRANCH_MISMATCH: 'Regenera evidencia en la rama actual antes de continuar.',
+  EVIDENCE_GATE_STATUS_INCOHERENT: 'Regenera evidencia para alinear ai_gate y severity_metrics.',
+  EVIDENCE_OUTCOME_INCOHERENT: 'Regenera evidencia para alinear ai_gate y snapshot.outcome.',
+  EVIDENCE_RULES_COVERAGE_MISSING: 'Ejecuta auditoría completa para recalcular rules_coverage.',
+  EVIDENCE_RULES_COVERAGE_STAGE_MISMATCH: 'Reanuda auditoría en el stage correcto.',
+  EVIDENCE_RULES_COVERAGE_INCOMPLETE:
+    'Asegura unevaluated=0 y coverage_ratio=1 antes de continuar.',
+  EVIDENCE_UNSUPPORTED_AUTO_RULES:
+    'Mapea todas las reglas AUTO a detectores AST antes de continuar.',
+  EVIDENCE_TIMESTAMP_FUTURE: 'Corrige la hora del sistema y regenera evidencia.',
+  GITFLOW_PROTECTED_BRANCH: 'Evita trabajo directo en ramas protegidas (usa feature/*).',
+};
+
+const buildPreFlightHints = (params: {
+  stage: AiGateStage;
+  status: ReturnType<typeof evaluateAiGate>['status'];
+  violations: ReadonlyArray<AiGateViolation>;
+  upstream: string | null;
+}): ReadonlyArray<string> => {
+  const hints: string[] = [];
+  const emittedCodes = new Set<string>();
+  for (const violation of params.violations) {
+    if (emittedCodes.has(violation.code)) {
+      continue;
+    }
+    const action = ACTIONABLE_HINTS_BY_CODE[violation.code];
+    if (!action) {
+      continue;
+    }
+    hints.push(`${violation.code}: ${action}`);
+    emittedCodes.add(violation.code);
+  }
+  if (params.stage === 'PRE_PUSH' && !params.upstream) {
+    hints.push('PRE_PUSH sin upstream: configura tracking (git push --set-upstream origin <branch>).');
+  }
+  if (hints.length === 0) {
+    if (params.status === 'ALLOWED') {
+      hints.push('Pre-flight operativo: sin bloqueos previos detectados.');
+    } else {
+      hints.push('Corrige la causa bloqueante y vuelve a ejecutar el pre-flight.');
+    }
+  }
+  return hints;
+};
+
+export type EnterprisePreFlightCheckResult = {
+  tool: 'pre_flight_check';
+  dryRun: true;
+  executed: true;
+  success: boolean;
+  result: {
+    allowed: ReturnType<typeof evaluateAiGate>['allowed'];
+    status: ReturnType<typeof evaluateAiGate>['status'];
+    stage: ReturnType<typeof evaluateAiGate>['stage'];
+    policy: ReturnType<typeof evaluateAiGate>['policy'];
+    violations: ReturnType<typeof evaluateAiGate>['violations'];
+    evidence: ReturnType<typeof evaluateAiGate>['evidence'];
+    mcp_receipt: ReturnType<typeof evaluateAiGate>['mcp_receipt'];
+    repo_state: ReturnType<typeof evaluateAiGate>['repo_state'];
+    hints: ReadonlyArray<string>;
+  };
+};
+
+export const runEnterprisePreFlightCheck = (params: {
+  repoRoot: string;
+  stage: AiGateStage;
+  requireMcpReceipt?: boolean;
+}): EnterprisePreFlightCheckResult => {
+  const evaluation = evaluateAiGate({
+    repoRoot: params.repoRoot,
+    stage: params.stage,
+    requireMcpReceipt: params.requireMcpReceipt ?? false,
+  });
+
+  const hints = buildPreFlightHints({
+    stage: evaluation.stage,
+    status: evaluation.status,
+    violations: evaluation.violations,
+    upstream: evaluation.repo_state.git.upstream,
+  });
+
+  return {
+    tool: 'pre_flight_check',
+    dryRun: true,
+    executed: true,
+    success: evaluation.allowed,
+    result: {
+      allowed: evaluation.allowed,
+      status: evaluation.status,
+      stage: evaluation.stage,
+      policy: evaluation.policy,
+      violations: evaluation.violations,
+      evidence: evaluation.evidence,
+      mcp_receipt: evaluation.mcp_receipt,
+      repo_state: evaluation.repo_state,
+      hints,
+    },
+  };
+};

package/integrations/notifications/emitAuditSummaryNotification.ts

@@ -133,3 +133,31 @@ export const emitAuditSummaryNotificationFromAiGate = (
     repoRoot: params.repoRoot,
   });
 };
+
+export const emitGateBlockedNotification = (
+  params: {
+    repoRoot: string;
+    stage: AuditSummaryNotificationStage;
+    totalViolations: number;
+    causeCode: string;
+    causeMessage: string;
+    remediation: string;
+  },
+  dependencies: Partial<AuditSummaryNotificationDependencies> = {}
+): SystemNotificationEmitResult => {
+  const activeDependencies: AuditSummaryNotificationDependencies = {
+    ...defaultDependencies,
+    ...dependencies,
+  };
+  return activeDependencies.emitSystemNotification({
+    event: {
+      kind: 'gate.blocked',
+      stage: params.stage,
+      totalViolations: params.totalViolations,
+      causeCode: params.causeCode,
+      causeMessage: params.causeMessage,
+      remediation: params.remediation,
+    },
+    repoRoot: params.repoRoot,
+  });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.37",
+  "version": "6.3.39",
   "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": {

package/scripts/framework-menu-consumer-preflight-lib.ts

@@ -154,10 +154,21 @@ const buildNotificationEvents = (result: AiGateCheckResult): ReadonlyArray<Pumuk
     });
   }
   if (result.status === 'BLOCKED') {
+    const firstViolation = result.violations[0];
+    const causeCode = firstViolation?.code ?? 'GATE_BLOCKED';
+    const causeMessage =
+      firstViolation?.message
+      ?? `Detected ${result.violations.length} blocking violations in stage ${result.stage}.`;
+    const remediation =
+      (firstViolation ? ACTIONABLE_HINTS_BY_CODE[firstViolation.code] : undefined)
+      ?? 'Corrige la causa bloqueante y vuelve a ejecutar el gate.';
     events.push({
       kind: 'gate.blocked',
       stage: result.stage,
       totalViolations: result.violations.length,
+      causeCode,
+      causeMessage,
+      remediation,
     });
   }
   return events;

package/scripts/framework-menu-evidence-summary-lib.ts

@@ -234,7 +234,7 @@ export const formatEvidenceSummaryForMenu = (
   if (summary.status === 'missing') {
     return [
       'Evidence: status=missing',
-      'Run `npx --yes pumuki-pre-commit` to generate fresh evidence.',
+      'Run `./node_modules/.bin/pumuki-pre-commit` to generate fresh evidence.',
     ].join('\n');
   }