pumuki 6.3.87 → 6.3.89

package/docs/operations/RELEASE_NOTES.md

@@ -1,3 +1,8 @@
+## 2026-04-20 (v6.3.89)
+- **Aislamiento por worktree**: `pumuki install` detecta worktrees sin `core.hooksPath` explícito y fija un `core.hooksPath` local a `.pumuki/git-hooks`, evitando que los hooks gestionados se escriban en `.git/hooks` del checkout principal compartido.
+- **Rollback limpio**: `pumuki uninstall` retira ese `core.hooksPath` solo si fue creado por Pumuki para el worktree.
+- **Rollout recomendado**: publicar `pumuki@6.3.89`, repin inmediato en `Flux_training` y repetir la repro de worktree (`install`, `bootstrap-manifest`, `status --json`, checksums de hooks en checkout principal).
+
 ## 2026-04-20 (v6.3.87)
 - Cierra el segundo tramo de PUM-026: si PRE_WRITE solo arregla el receipt MCP y el gate pasa a verde, fuerza un refresh de paridad contra PRE_COMMIT antes del veredicto final.
 - Rollout recomendado: actualizar Flux_training y repetir la repro mínima de validate/pre-commit/.ai_evidence.
@@ -814,3 +819,5 @@ This file keeps only the operational highlights and rollout notes that matter wh
 
 - Legacy 5.3.4 migration/release notes were removed from active docs to avoid drift.
 - Historical commit trace remains available in Git history.
+
+- 6.3.88: PUM-027 cierra el caso MCP degradado; sin .pumuki/adapter.json el gate bloquea y ya no regenera mcp-ai-gate-receipt.

package/integrations/lifecycle/hookManager.ts

@@ -27,6 +27,81 @@ export type PumukiHooksDirectoryResolution = {
 };
 
 const HOOK_FILE_MODE = 0o755;
+const PUMUKI_WORKTREE_HOOKS_PATH = '.pumuki/git-hooks';
+
+const readLocalGitConfigValue = (repoRoot: string, key: string): string | null => {
+  try {
+    const value = execFileSync('git', ['config', '--local', '--get', key], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return value.length > 0 ? value : null;
+  } catch {
+    return null;
+  }
+};
+
+const writeLocalGitConfigValue = (repoRoot: string, key: string, value: string): void => {
+  execFileSync('git', ['config', '--local', key, value], {
+    cwd: repoRoot,
+    stdio: ['ignore', 'ignore', 'ignore'],
+  });
+};
+
+const unsetLocalGitConfigValue = (repoRoot: string, key: string): void => {
+  try {
+    execFileSync('git', ['config', '--local', '--unset-all', key], {
+      cwd: repoRoot,
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+  } catch {
+    // noop
+  }
+};
+
+const isWorktreeCheckout = (repoRoot: string): boolean => {
+  try {
+    const gitPointer = readFileSync(join(repoRoot, '.git'), 'utf8').trim();
+    return /^gitdir:\s+/i.test(gitPointer);
+  } catch {
+    return false;
+  }
+};
+
+const isPumukiManagedWorktreeHooksPath = (repoRoot: string, hooksPath: string): boolean => {
+  const normalizedHooksPath = hooksPath.trim();
+  return (
+    normalizedHooksPath === PUMUKI_WORKTREE_HOOKS_PATH ||
+    normalizedHooksPath === resolve(repoRoot, PUMUKI_WORKTREE_HOOKS_PATH)
+  );
+};
+
+const ensureWorktreeLocalHooksPath = (repoRoot: string): void => {
+  if (!isWorktreeCheckout(repoRoot)) {
+    return;
+  }
+
+  const currentHooksPath = readLocalGitConfigValue(repoRoot, 'core.hooksPath');
+  if (currentHooksPath) {
+    return;
+  }
+
+  writeLocalGitConfigValue(repoRoot, 'core.hooksPath', PUMUKI_WORKTREE_HOOKS_PATH);
+};
+
+const clearWorktreeLocalHooksPath = (repoRoot: string): void => {
+  if (!isWorktreeCheckout(repoRoot)) {
+    return;
+  }
+
+  const currentHooksPath = readLocalGitConfigValue(repoRoot, 'core.hooksPath');
+  if (!currentHooksPath || !isPumukiManagedWorktreeHooksPath(repoRoot, currentHooksPath)) {
+    return;
+  }
+
+  unsetLocalGitConfigValue(repoRoot, 'core.hooksPath');
+};
 
 const resolveGitPath = (repoRoot: string, gitPathTarget: string): string | null => {
   try {
@@ -137,6 +212,7 @@ const ensureHooksDirectory = (repoRoot: string): void => {
 };
 
 export const installPumukiHooks = (repoRoot: string): HookInstallResult => {
+  ensureWorktreeLocalHooksPath(repoRoot);
   ensureHooksDirectory(repoRoot);
   const changedHooks: PumukiManagedHook[] = [];
 
@@ -180,6 +256,7 @@ export const uninstallPumukiHooks = (repoRoot: string): HookUninstallResult => {
     changedHooks.push(hook);
   }
 
+  clearWorktreeLocalHooksPath(repoRoot);
   return { changedHooks };
 };
 

package/integrations/lifecycle/preWriteAutomation.ts

@@ -68,16 +68,24 @@ const hasAutoFixableEvidenceViolation = (aiGate: ReturnType<typeof evaluateAiGat
 const hasEvidenceGateBlockedViolation = (aiGate: ReturnType<typeof evaluateAiGate>): boolean =>
   aiGate.violations.some((violation) => violation.code === 'EVIDENCE_GATE_BLOCKED');
 
+const hasAdapterMissingViolation = (aiGate: ReturnType<typeof evaluateAiGate>): boolean =>
+  aiGate.violations.some((violation) => violation.code === 'MCP_ENTERPRISE_ADAPTER_MISSING');
+
 const hasAutoFixableMcpReceiptViolation = (aiGate: ReturnType<typeof evaluateAiGate>): boolean =>
-  aiGate.violations.some((violation) => PRE_WRITE_AUTOFIXABLE_MCP_RECEIPT_CODES.has(violation.code));
+  !hasAdapterMissingViolation(aiGate)
+  && aiGate.violations.some((violation) => PRE_WRITE_AUTOFIXABLE_MCP_RECEIPT_CODES.has(violation.code));
 
 const collectAutoFixableViolationCodes = (aiGate: ReturnType<typeof evaluateAiGate>): string[] =>
   aiGate.violations
-    .filter(
-      (violation) =>
-        PRE_WRITE_AUTOFIXABLE_EVIDENCE_CODES.has(violation.code)
-        || PRE_WRITE_AUTOFIXABLE_MCP_RECEIPT_CODES.has(violation.code)
-    )
+    .filter((violation) => {
+      if (PRE_WRITE_AUTOFIXABLE_EVIDENCE_CODES.has(violation.code)) {
+        return true;
+      }
+      if (!PRE_WRITE_AUTOFIXABLE_MCP_RECEIPT_CODES.has(violation.code)) {
+        return false;
+      }
+      return !hasAdapterMissingViolation(aiGate);
+    })
     .map((violation) => violation.code)
     .sort((left, right) => left.localeCompare(right));
 

package/integrations/mcp/aiGateCheck.ts

@@ -1,3 +1,5 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { evaluateAiGate, type AiGateStage } from '../gate/evaluateAiGate';
 import { resolveRemediationHintForViolationCode } from '../gate/remediationCatalog';
 import { resolveLearningContextExperimentalFeature } from '../policy/experimentalFeatures';
@@ -48,6 +50,8 @@ const HOOK_STAGE_SET = new Set<AiGateStage>(['PRE_COMMIT', 'PRE_PUSH', 'CI']);
 const isHookRefreshableEvidenceCode = (code: string): boolean =>
   code.startsWith('EVIDENCE_');
 
+const MCP_ENTERPRISE_ADAPTER_MISSING_CODE = 'MCP_ENTERPRISE_ADAPTER_MISSING';
+
 type AiGateCheckDependencies = {
   evaluateAiGate: typeof evaluateAiGate;
   runMcpAlignedPlatformGate: typeof runMcpAlignedPlatformGate;
@@ -120,6 +124,9 @@ const buildAutoFixes = (
   learningContext: SddLearningContext | null
 ): ReadonlyArray<string> => {
   const fixes: string[] = [];
+  if (evaluation.violations.some((violation) => violation.code === MCP_ENTERPRISE_ADAPTER_MISSING_CODE)) {
+    fixes.push('Regenera .pumuki/adapter.json con `pnpm exec pumuki install` antes de volver a validar el gate MCP.');
+  }
   const emittedCodes = new Set<string>();
   for (const violation of evaluation.violations) {
     if (emittedCodes.has(violation.code)) {
@@ -163,6 +170,39 @@ const resolveAiGateCheckMode = (): PlatformGateAlignment['mode'] => {
   return raw === 'full' || raw === 'aligned' ? 'full' : 'policy';
 };
 
+const hasMcpAdapter = (repoRoot: string): boolean =>
+  existsSync(join(repoRoot, '.pumuki', 'adapter.json'));
+
+const withRequiredMcpAdapter = (
+  evaluation: ReturnType<typeof evaluateAiGate>,
+  repoRoot: string,
+  requireMcpReceipt: boolean
+): ReturnType<typeof evaluateAiGate> => {
+  if (!requireMcpReceipt || hasMcpAdapter(repoRoot)) {
+    return evaluation;
+  }
+  if (evaluation.violations.some((violation) => violation.code === MCP_ENTERPRISE_ADAPTER_MISSING_CODE)) {
+    return {
+      ...evaluation,
+      allowed: false,
+      status: 'BLOCKED',
+    };
+  }
+  return {
+    ...evaluation,
+    allowed: false,
+    status: 'BLOCKED',
+    violations: [
+      {
+        code: MCP_ENTERPRISE_ADAPTER_MISSING_CODE,
+        severity: 'ERROR',
+        message: 'Missing .pumuki/adapter.json. MCP-dependent validation cannot prove a real MCP invocation.',
+      },
+      ...evaluation.violations,
+    ],
+  };
+};
+
 const toPlatformGateAlignment = (
   mode: PlatformGateAlignment['mode'],
   platform?: { exitCode: number; aligned: boolean; skipReason: string | null }
@@ -192,40 +232,45 @@ 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 normalizedEvaluation = withRequiredMcpAdapter(
+    evaluation,
+    params.repoRoot,
+    params.requireMcpReceipt ?? false
+  );
+  const branch = normalizedEvaluation.repo_state.git.branch;
+  const timestamp = normalizedEvaluation.evidence.source.generated_at;
   const learningContextFeature = resolveLearningContextExperimentalFeature();
   const learningContext = learningContextFeature.mode === 'off'
     ? null
     : readSddLearningContext({
       repoRoot: params.repoRoot,
     });
-  const warnings = buildWarnings(evaluation);
-  const autoFixes = buildAutoFixes(evaluation, learningContext);
-  const message = buildMessage(evaluation);
+  const warnings = buildWarnings(normalizedEvaluation);
+  const autoFixes = buildAutoFixes(normalizedEvaluation, learningContext);
+  const message = buildMessage(normalizedEvaluation);
 
   return {
     tool: 'ai_gate_check',
     dryRun: true,
     executed: true,
-    success: evaluation.allowed,
+    success: normalizedEvaluation.allowed,
     result: {
-      allowed: evaluation.allowed,
-      status: evaluation.status,
+      allowed: normalizedEvaluation.allowed,
+      status: normalizedEvaluation.status,
       timestamp,
       branch,
       message,
-      stage: evaluation.stage,
-      policy: evaluation.policy,
-      violations: evaluation.violations,
+      stage: normalizedEvaluation.stage,
+      policy: normalizedEvaluation.policy,
+      violations: normalizedEvaluation.violations,
       warnings,
       auto_fixes: autoFixes,
       learning_context: learningContext,
-      evidence: evaluation.evidence,
-      mcp_receipt: evaluation.mcp_receipt,
-      skills_contract: evaluation.skills_contract,
-      repo_state: evaluation.repo_state,
-      consistency_hint: buildConsistencyHint(evaluation),
+      evidence: normalizedEvaluation.evidence,
+      mcp_receipt: normalizedEvaluation.mcp_receipt,
+      skills_contract: normalizedEvaluation.skills_contract,
+      repo_state: normalizedEvaluation.repo_state,
+      consistency_hint: buildConsistencyHint(normalizedEvaluation),
     },
   };
 };
@@ -245,6 +290,11 @@ export const runEnterpriseAiGateCheckAsync = async (params: {
     stage: params.stage,
     requireMcpReceipt: params.requireMcpReceipt ?? false,
   });
+  const normalizedEvaluation = withRequiredMcpAdapter(
+    evaluation,
+    params.repoRoot,
+    params.requireMcpReceipt ?? false
+  );
 
   let platform:
     | { exitCode: number; aligned: boolean; skipReason: string | null }
@@ -257,11 +307,11 @@ export const runEnterpriseAiGateCheckAsync = async (params: {
   }
 
   const platformBlocks = Boolean(platform && platform.exitCode !== 0);
-  const allowed = evaluation.allowed && !platformBlocks;
+  const allowed = normalizedEvaluation.allowed && !platformBlocks;
   const status: 'ALLOWED' | 'BLOCKED' = allowed ? 'ALLOWED' : 'BLOCKED';
   const violations = platformBlocks && platform
     ? [
-      ...evaluation.violations,
+      ...normalizedEvaluation.violations,
       {
         code: 'PLATFORM_GATE_EXIT_NON_ZERO',
         message:
@@ -270,16 +320,16 @@ export const runEnterpriseAiGateCheckAsync = async (params: {
         severity: 'ERROR' as const,
       },
     ]
-    : evaluation.violations;
-  const branch = evaluation.repo_state.git.branch;
-  const timestamp = evaluation.evidence.source.generated_at;
+    : normalizedEvaluation.violations;
+  const branch = normalizedEvaluation.repo_state.git.branch;
+  const timestamp = normalizedEvaluation.evidence.source.generated_at;
   const learningContextFeature = resolveLearningContextExperimentalFeature();
   const learningContext = learningContextFeature.mode === 'off'
     ? null
     : readSddLearningContext({
       repoRoot: params.repoRoot,
     });
-  const evaluationForHints = { ...evaluation, allowed, status, violations };
+  const evaluationForHints = { ...normalizedEvaluation, allowed, status, violations };
   const warnings = buildWarnings(evaluationForHints);
   const autoFixes = buildAutoFixes(evaluationForHints, learningContext);
   const message = buildMessage(evaluationForHints, platform);
@@ -295,16 +345,16 @@ export const runEnterpriseAiGateCheckAsync = async (params: {
       timestamp,
       branch,
       message,
-      stage: evaluation.stage,
-      policy: evaluation.policy,
+      stage: normalizedEvaluation.stage,
+      policy: normalizedEvaluation.policy,
       violations,
       warnings,
       auto_fixes: autoFixes,
       learning_context: learningContext,
-      evidence: evaluation.evidence,
-      mcp_receipt: evaluation.mcp_receipt,
-      skills_contract: evaluation.skills_contract,
-      repo_state: evaluation.repo_state,
+      evidence: normalizedEvaluation.evidence,
+      mcp_receipt: normalizedEvaluation.mcp_receipt,
+      skills_contract: normalizedEvaluation.skills_contract,
+      repo_state: normalizedEvaluation.repo_state,
       consistency_hint: buildConsistencyHint(evaluationForHints, platform),
       platform_gate_alignment: toPlatformGateAlignment(mode, platform),
     },

package/package.json

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